Authoring an extension
This walks through building writing-companion, the bundle that ships with TF
Code. Every file below is complete — copy it, and it works.
TypeScript is transpiled in-process. Save a .ts file and it runs on the next
session. There is no npm run build, and TF Code does not require Bun or Node
to be installed.
1. Scaffold
tfcode extension new writing-companion --template writing-companion
Or from scratch, which writes a minimal working bundle:
tfcode extension new writing-companion
Then link it, so your edits are live:
tfcode extension link writing-companion
link records the source path and reads through it — no copy. install copies
into the store when you want a fixed snapshot.
2. The manifest
tfcode-extension.json:
{
"name": "writing-companion",
"version": "1.0.0",
"description": "A writing-focused bundle",
"contextFileName": ["TFCODE.md", "STYLE.md"]
}
Enable the perk in your project's tfcode.json:
{ "perks": { "extensions": true } }
3. Context
TFCODE.md is injected into the system prompt on every session while the
extension is enabled. Keep it short — it is context on every request, not
documentation.
# writing-companion
This project is a writing project. Prefer editing existing prose over rewriting
it, and always preserve the author's voice.
Declare additional files with contextFileName (as above) when one file would
get unwieldy.
4. A command
commands/writing/polish.md — the path below commands/ becomes the name, so
this is /writing:polish:
---
description: Tighten prose without changing its meaning
agent: build
---
Polish the following so it is clearer and shorter, keeping the author's voice
and every fact. Show the revised text, then a short list of what you changed.
$ARGUMENTS
Placeholders:
| Placeholder | Replaced with |
|---|---|
$ARGUMENTS | everything the user typed after the command |
$1, $2, … | the positional arguments; the last one swallows the rest |
| neither | the arguments are appended below the template |
Frontmatter keys: description, agent, model, subtask.
5. A subagent
agents/writer.md — frontmatter plus the prompt body:
---
description: Drafts and revises long-form prose in the house style
mode: subagent
---
You are an editor working inside this project.
- Read `STYLE.md` before editing anything substantial.
- Preserve the author's argument and voice.
- Report what you changed as a short list.
6. A skill
skills/house-style/SKILL.md — loaded on demand, not on every request:
---
name: house-style
description: The project's writing rules — use when tightening or reviewing prose
---
# House style
1. Prefer the concrete over the abstract.
2. One idea per sentence.
3. Cut intensifiers: very, really, quite, actually, basically.
Skills can ship references/ and scripts/ beside SKILL.md; both are
materialised to disk so a script is runnable.
7. A tool
tools/count-words.ts. A tool file is a plugin: it exports a factory
returning hooks, and registers tools under tool.
export default async () => ({
tool: {
count_words: {
description: "Count words, sentences and reading time for a passage.",
args: {
text: { type: "string", description: "The passage to measure" },
},
async execute(args: { text?: string }) {
const text = (args.text ?? "").trim()
const words = text.split(/\s+/).filter(Boolean).length
return `${words} words`
},
},
},
})
The key (count_words) is the id the model calls. args is the JSON schema the
model sees — it is not Zod, it is plain JSON Schema.
If your id collides with bash, read, edit or any other builtin, yours is
ignored and a warning is logged. Pick a namespaced id.
8. A hook
hooks/guard.ts. The same file shape, but implementing a hook instead of
registering a tool:
const DENY = [/rm\s+-[a-zA-Z]*r[a-zA-Z]*f\s+\/(\s|$)/]
export default async () => ({
"tool.execute.before": async (input: any, output: any) => {
if (input.tool !== "bash") return
const command: string = output?.args?.command ?? ""
if (DENY.some((re) => re.test(command))) {
// throwing BLOCKS the call; the message is what the model sees
throw new Error("Blocked: this command looks destructive. Ask the user first.")
}
},
})
Hooks receive (input, output) and mutate output. Throwing is how you block.
The seven hooks available in this version:
| Hook | When | What you can change |
|---|---|---|
tool | registration | add tools |
tool.execute.before | before a tool runs | output.args; throw to block |
tool.execute.after | after a tool runs | output.title, output.output, output.metadata |
shell.env | before bash runs | output.env (add environment variables) |
event | session lifecycle | nothing — for side effects |
experimental.chat.system.transform | prompt assembly | output.system (append context) |
chat.message | user message created | output.parts (rewrite text) |
Lifecycle aliases work too, so a Matilda or Claude hooks.json keeps running:
PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop,
SessionStart, SessionEnd, Notification.
9. An MCP server
{
"mcpServers": {
"notes": {
"type": "local",
"command": ["node", "server.js"]
}
}
}
Same shape as tfcode.json → mcp, and the same approval gate applies: an
extension server is challenged before it launches.
The server is mounted under a namespaced key, <extension>__<server> — here
notes becomes my-extension__notes. Two extensions can therefore both declare
a notes server without colliding, and the name you see in a server list is not
the key you wrote. Read the effective key back rather than assuming it:
curl -s -H "x-opencode-directory: $PWD" localhost:4096/config | jq '.mcp | keys'
10. An LSP server
{
"lspServers": {
"prose": {
"command": ["prose-lsp"],
"extensions": [".md"]
}
}
}
Same namespacing (my-extension__prose) and the same tfcode.json → lsp
shape. GET /lsp lists only servers that are already connected, so an
extension LSP that has not been asked about a matching file yet shows up in
GET /config → lsp but not in GET /lsp. Absence there is not a failure.
11. Debugging
tfcode extension list # state: enabled / disabled / needs approval / inert
tfcode extension list --json # digests, contributions, last runtime error
tfcode extension pending # what is waiting for a decision
A plugin that fails to load is reported, not swallowed: list --json carries
error and lastError, and the server logs the plugin name with the failure.
Verify every surface — discovery is not wiring
extension list --json reports what was discovered. It does not prove each
surface is actually reached by the session. A manifest can claim eight
contributions and have three of them dead, and nothing errors — this is the
single most common way an extension "works" while doing nothing.
Each surface has its own endpoint. Query them all, with the project directory set:
H="x-opencode-directory: $PWD"
curl -s -H "$H" localhost:4096/command | jq -r '.[].name' # slash commands
curl -s -H "$H" localhost:4096/agent | jq -r '.[].name' # subagents
curl -s -H "$H" localhost:4096/skill | jq -r '.[].name' # skills
curl -s -H "$H" "localhost:4096/experimental/tool?provider=toothfairyai&model=mystica_15" \
| jq -r '.[].id' # tools
curl -s -H "$H" localhost:4096/config | jq '.mcp, .lsp' # MCP + LSP
x-opencode-directory is not optional. Without it the server uses the global
project, which has no config file — so the perk and trust gates fail and every
one of those routes returns an empty list with a 200. An empty result and no
error is almost always the missing header, not a broken extension.
12. Publish
Any directory with a manifest is installable. Push it to git and a colleague runs:
tfcode extension install https://github.com/you/writing-companion
tfcode extension approve writing-companion
Next
- Extension reference — every field, hook shape and error string
- Migrating — bring an existing extension over