Skip to main content
Version: v3

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.

No build step

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:

PlaceholderReplaced with
$ARGUMENTSeverything the user typed after the command
$1, $2, …the positional arguments; the last one swallows the rest
neitherthe 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.

Tool ids cannot shadow builtins

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:

HookWhenWhat you can change
toolregistrationadd tools
tool.execute.beforebefore a tool runsoutput.args; throw to block
tool.execute.afterafter a tool runsoutput.title, output.output, output.metadata
shell.envbefore bash runsoutput.env (add environment variables)
eventsession lifecyclenothing — for side effects
experimental.chat.system.transformprompt assemblyoutput.system (append context)
chat.messageuser message createdoutput.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
warning

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​