Extension reference
The exhaustive surface. Every example here is validated by a test, so if this page drifts from the code the build fails.
Manifest fields
tfcode-extension.json, in the extension root.
| Field | Type | Default | Effect |
|---|---|---|---|
name | string | — (required) | [a-z0-9-]{1,64}. Used for enablement, the trust key and the store path |
version | string | "1.0.0" | Included in the digest; bumping it re-prompts for approval |
description | string | "" | Shown in extension list and the web panel |
contextFileName | string | string[] | "TFCODE.md" | Files injected into the system prompt |
mcpServers | object | {} | MCP servers, same shape as tfcode.json → mcp |
lspServers | object | {} | LSP servers, same shape as tfcode.json → lsp |
hooks | object | {} | Declares which lifecycle hooks this bundle implements |
Unknown fields are an error, not a silent ignore — a typo'd field would otherwise produce a bundle that looks fine and does nothing.
Hooks
Input and output
Every hook is async (input, output) => void. Mutate output; throw to abort.
| Hook | input | output |
|---|---|---|
tool | — (declaration only) | — |
tool.execute.before | { tool, sessionID, callID } | { args } |
tool.execute.after | { tool, sessionID, callID, args } | { title, output, metadata } |
shell.env | { cwd, sessionID } | { env } |
event | { event: { type, properties } } | {} |
experimental.chat.system.transform | { sessionID, model } | { system: string[] } |
chat.message | { sessionID, agent, model, messageID } | { message, parts } |
Lifecycle aliases
| Alias | Canonical hook |
|---|---|
PreToolUse | tool.execute.before |
PostToolUse | tool.execute.after |
PostToolUseFailure | tool.execute.after |
UserPromptSubmit | chat.message |
Stop | event |
SessionStart | event |
SessionEnd | event |
Notification | event |
Not supported in this version
These exist in the wider plugin API but are not dispatched yet. Declaring one is reported, never silently ignored:
auth, config, chat.params, chat.headers, permission.ask,
command.execute.before, tool.definition,
experimental.chat.messages.transform, experimental.session.compacting,
experimental.text.complete, UserPromptExpansion, PreCompact,
SubagentStart, SubagentStop, PermissionRequest, PostToolBatch,
Directories.
Variables
| Variable | Resolves to |
|---|---|
${extensionPath} | the extension's own directory |
${workspacePath} | the project directory |
${/} | the path separator for this platform |
${pathSeparator} | alias for ${/} |
An unknown ${…} is left verbatim rather than blanked — a blank path produces a
confusing "file not found" later.
CLI
tfcode extension (alias tfcode ext).
| Command | Effect |
|---|---|
list [--json] | installed extensions and their per-project state |
install <source> | copy a local directory or clone a git URL into the store |
uninstall <name> | remove from the store |
link <path> | track a source directory; edits are live |
enable <name> | enable for the current project |
disable <name> | disable for the current project |
new <path> [--template] | scaffold; available templates: hello-tool, guardrails, writing-companion |
import <path> | convert a Matilda / Gemini / Claude manifest |
approve <name> | trust a code-bearing extension at its current digest |
reject <name> | refuse it, remembered per digest |
pending | list extensions awaiting a decision |
Exit codes
| Code | Meaning |
|---|---|
| 0 | success |
| 1 | runtime error (bad manifest, unreadable path, not installed) |
HTTP
| Route | Method | Effect |
|---|---|---|
/extension | GET | all installed extensions with state |
/extension/{name} | GET | one extension's manifest and contributions |
/extension/{name}/enable | POST | enable for the project in x-opencode-directory |
/extension/{name}/disable | POST | disable for that project |
All four require perks.extensions; with the perk off they answer 403 rather
than leaking what is installed.
Enablement
.tfcode/extensions.json in the project root:
{ "disabled": ["noisy-extension"] }
Installed means enabled. That list is the whole opt-out mechanism — there is no rule language.
Trust
A code-bearing extension (one with tools/, hooks/, mcpServers or
lspServers) needs a decision before it runs.
- The decision is keyed by digest and by project.
- The digest covers the manifest's semantic content plus every contributed file.
.envis excluded: rotating a secret is not a definition change.- Editing any contributed file changes the digest, which revokes the approval.
- A corrupt trust store reads as no decision, never as approved.
- A non-interactive run refuses to load an undecided extension instead of assuming consent.
The store is <data>/extension-trust.json, written with write-then-rename.
Errors
| Message | Cause | Fix |
|---|---|---|
manifest is not valid JSON | syntax error | validate the file |
manifest is missing \name`` | no name field | add one |
`name` may only contain lowercase letters, digits and `-` | illegal characters | rename |
no tfcode-extension.json in <dir> | not an extension | add the manifest |
<name> is already installed | store collision | uninstall first, or link |
no importable manifest in <path> | unrecognised source format | see Migrating |
plugin eval failed: … | the tool/hook file does not compile | fix the TypeScript; the message carries the line |
tool not registered | the io id does not match the tool key | align them |
Blocked by … | a hook threw | that is the hook working |
Where things live
| Path | Contents |
|---|---|
<data>/extensions/<name>/ | installed (copied) extensions |
<data>/extensions/<name>/installed.json | origin, spec, version |
<data>/extension-trust.json | per-project trust decisions |
<cache>/plugin-bundles/<sha256>.js | transpiled plugin output |
.tfcode/extensions.json | per-project disable list |