Skip to main content
Version: v3

Extensions

An extension is one installable unit that can ship tools, slash commands, subagents, skills, hooks, MCP servers, LSP servers and standing context together. It is versioned, enableable per project, and gated behind an explicit trust decision because it can run code.

An extension is a distribution unit, not a new runtime. Everything it contributes flows into a loader that already exists.

Which one do I want?​

TF Code has several ways to extend behaviour, and the names overlap. This table is the short answer.

You want to…UseLives inNeeds code?
Teach the agent a workflowSkill.tfcode/skill/<name>/SKILL.mdno
Add a slash commandCommand.tfcode/command/<name>.mdno
Add a subagentAgent.tfcode/agent/<name>.mdno
Add a tool or hookPlugin.tfcode/plugin/*.tsyes
Turn a capability on/offPerktfcode.json → perksno
Ship all of the above as one thingExtensiontfcode-extension.jsonmaybe

Skills, commands and agents are markdown: the agent reads them, no code runs. Plugins are code. An extension is the packaging: it may contain any of the above.

Start here

If you only want to add one tool, you do not need an extension. Drop a .ts file in .tfcode/tool/ (see Tools) or a plugin in .tfcode/plugin/ (see Plugins). Reach for an extension when you want to share a set of behaviours with someone else.

What an extension can ship​

my-extension/
├── tfcode-extension.json # the manifest
├── TFCODE.md # context injected into the system prompt
├── commands/ # **/*.md → slash commands
├── agents/ # **/*.md → subagents
├── skills/ # <name>/SKILL.md → skills
├── tools/ # *.ts | *.js → tools
├── hooks/ # *.ts | *.js → hooks
└── scripts/ # resources; ${extensionPath} resolves here

Every contribution is optional. A bundle with only a TFCODE.md is a valid extension and needs no trust decision, because no code runs.

The manifest​

{
"name": "writing-companion",
"version": "1.0.0",
"description": "A writing-focused bundle",
"contextFileName": ["TFCODE.md", "STYLE.md"],
"mcpServers": {},
"lspServers": {},
"hooks": {}
}
FieldRequiredMeaning
nameyeslowercase letters, digits and -, 1–64 characters
versionnodefaults to 1.0.0; changing it changes the trust digest
descriptionnoshown in extension list and the web panel
contextFileNamenofile or files injected into the system prompt (default TFCODE.md)
mcpServersnoMCP servers, same shape as tfcode.json → mcp
lspServersnoLSP servers, same shape as tfcode.json → lsp
hooksnowhich lifecycle hooks this bundle implements

Lifecycle​

stateDiagram-v2
[*] --> Discovered
Discovered --> NeedsTrust: ships code (tools/ or hooks/)
Discovered --> Enabled: context-only, or already approved
NeedsTrust --> Enabled: you approve
NeedsTrust --> Rejected: you reject
Enabled --> NeedsTrust: any contributed file changes
Enabled --> Disabled: disabled for this project
Disabled --> Enabled: enabled again

The step people are surprised by is Enabled → NeedsTrust. The digest covers every contributed file, not just the manifest, so editing one line of a hook asks for approval again. That is deliberate: an approval is for what you reviewed, and a silent edit is exactly the attack an approval gate exists to stop.

Precedence​

When an extension and a project file collide, the project wins:

  1. .tfcode/command, .tfcode/agent, .tfcode/skill — hand-written, highest
  2. extension contributions — fill gaps
  3. builtin commands, then skills — fill remaining gaps

So you can install an extension and override any single piece of it locally without forking it.

Turning it on​

Extensions are behind a perk, off by default:

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

With the perk off the store is not scanned at all — an installed extension is listed as inert, so nothing is running invisibly.

Next​