Skip to main content
Version: v3

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.

FieldTypeDefaultEffect
namestring— (required)[a-z0-9-]{1,64}. Used for enablement, the trust key and the store path
versionstring"1.0.0"Included in the digest; bumping it re-prompts for approval
descriptionstring""Shown in extension list and the web panel
contextFileNamestring | string[]"TFCODE.md"Files injected into the system prompt
mcpServersobject{}MCP servers, same shape as tfcode.json → mcp
lspServersobject{}LSP servers, same shape as tfcode.json → lsp
hooksobject{}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.

Hookinputoutput
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​

AliasCanonical hook
PreToolUsetool.execute.before
PostToolUsetool.execute.after
PostToolUseFailuretool.execute.after
UserPromptSubmitchat.message
Stopevent
SessionStartevent
SessionEndevent
Notificationevent

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​

VariableResolves 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).

CommandEffect
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
pendinglist extensions awaiting a decision

Exit codes​

CodeMeaning
0success
1runtime error (bad manifest, unreadable path, not installed)

HTTP​

RouteMethodEffect
/extensionGETall installed extensions with state
/extension/{name}GETone extension's manifest and contributions
/extension/{name}/enablePOSTenable for the project in x-opencode-directory
/extension/{name}/disablePOSTdisable 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.
  • .env is 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​

MessageCauseFix
manifest is not valid JSONsyntax errorvalidate the file
manifest is missing \name``no name fieldadd one
`name` may only contain lowercase letters, digits and `-`illegal charactersrename
no tfcode-extension.json in <dir>not an extensionadd the manifest
<name> is already installedstore collisionuninstall first, or link
no importable manifest in <path>unrecognised source formatsee Migrating
plugin eval failed: …the tool/hook file does not compilefix the TypeScript; the message carries the line
tool not registeredthe io id does not match the tool keyalign them
Blocked by …a hook threwthat is the hook working

Where things live​

PathContents
<data>/extensions/<name>/installed (copied) extensions
<data>/extensions/<name>/installed.jsonorigin, spec, version
<data>/extension-trust.jsonper-project trust decisions
<cache>/plugin-bundles/<sha256>.jstranspiled plugin output
.tfcode/extensions.jsonper-project disable list