Skip to main content
Version: v3

Extensions

An extension is one installable bundle that can add tools, slash commands, subagents, skills, hooks, MCP servers and standing context to TF Code at once. It is versioned, enableable per project, and gated behind an explicit trust decision because it can run code.

This page is the user-facing side: installing, enabling and trusting. For building one, see the authoring guide.

Enable the capability​

Extensions are behind a perk, off by default:

{ "perks": { "extensions": true } }

With the perk off, an installed extension is listed as inert and contributes nothing. Nothing runs invisibly.

Install​

# from a local directory you will keep editing (edits are live)
tfcode extension link ~/src/writing-companion

# copy a snapshot into the store
tfcode extension install ~/src/writing-companion

# from a git repository
tfcode extension install https://github.com/you/writing-companion

See what is installed​

tfcode extension list
Extensions (2)
writing-companion v1.0.0 [enabled]
1 command, 1 agent, 1 skill, 1 tool
guardrails v1.0.0 [needs approval]
1 hook
run: tfcode extension approve guardrails (this extension can run code)

The state in brackets answers "why is nothing happening":

StateMeaning
enabledcontributing
disabled for this projectyou turned it off here
needs approvalit ships code and has not been trusted at this version
inert (perks.extensions is off)the capability is off

For machine-readable output, including digests and the last runtime error:

tfcode extension list --json

What "can run code" means​

A bundle whose only content is markdown (TFCODE.md, commands/, agents/, skills/) executes nothing — it just adds text the agent reads. It needs no approval.

A bundle with tools/, hooks/, mcpServers or lspServers runs programs: your tools execute in the extension runtime, hooks intercept tool calls, MCP and LSP servers are launched as processes. Those require a decision.

tfcode extension approve guardrails

Why approval is keyed by content​

approve records the extension's digest, which covers the manifest and every contributed file. That has one visible consequence:

Editing a line of an extension's code revokes its approval and asks again.

This is not friction for its own sake. You approved what you reviewed. If an extension can change itself after approval — a git pull, an editor save — the approval no longer means anything. .env is excluded, so rotating a secret does not re-prompt.

Decisions are per project: approving an extension in one checkout does not approve it in another.

Enable and disable per project​

tfcode extension disable guardrails # just this project
tfcode extension enable guardrails

Stored in .tfcode/extensions.json:

{ "disabled": ["guardrails"] }

Commit that file if the whole team should skip the extension in this repo.

Non-interactive runs​

A CI job or a headless run will not silently accept an undecided extension. It refuses to load it and exits with an error naming the extension. Approve it in the project once, interactively, and the decision persists.

Removing​

tfcode extension uninstall writing-companion

Next​