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… | Use | Lives in | Needs code? |
|---|---|---|---|
| Teach the agent a workflow | Skill | .tfcode/skill/<name>/SKILL.md | no |
| Add a slash command | Command | .tfcode/command/<name>.md | no |
| Add a subagent | Agent | .tfcode/agent/<name>.md | no |
| Add a tool or hook | Plugin | .tfcode/plugin/*.ts | yes |
| Turn a capability on/off | Perk | tfcode.json → perks | no |
| Ship all of the above as one thing | Extension | tfcode-extension.json | maybe |
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.
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": {}
}
| Field | Required | Meaning |
|---|---|---|
name | yes | lowercase letters, digits and -, 1–64 characters |
version | no | defaults to 1.0.0; changing it changes the trust digest |
description | no | shown in extension list and the web panel |
contextFileName | no | file or files injected into the system prompt (default TFCODE.md) |
mcpServers | no | MCP servers, same shape as tfcode.json → mcp |
lspServers | no | LSP servers, same shape as tfcode.json → lsp |
hooks | no | which 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:
.tfcode/command,.tfcode/agent,.tfcode/skill— hand-written, highest- extension contributions — fill gaps
- 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
- Authoring an extension — build one, start to finish
- Extension reference — every field, hook and error
- Migrating — from Matilda, Claude or Gemini