Migrating an extension
tfcode extension import <path> reads a foreign manifest and writes a
tfcode-extension.json beside it. It maps the fields that carry over and
reports what it dropped rather than losing it silently.
Matilda
matilda-extension.json:
{
"name": "writing-companion",
"version": "1.4.2",
"description": "Writing tools",
"contextFileName": "CONTEXT.md",
"mcpServers": { "notes": { "command": ["node", "notes.js"] } }
}
Becomes:
{
"name": "writing-companion",
"version": "1.4.2",
"description": "Writing tools",
"contextFileName": "CONTEXT.md",
"mcpServers": { "notes": { "command": ["node", "notes.js"] } }
}
What maps directly: name, version, description, contextFileName,
mcpServers, lspServers, hooks.
What does not: Matilda's settings block, its extension-enablement.json rule
language, and its Directories behaviour (symlinking directories into
worktrees). TF Code uses a plain disable list instead — see
Extensions.
Claude
.claude-plugin/plugin.json:
{
"name": "house-tools",
"version": "0.3.0",
"description": "House conventions"
}
The directory layout already matches: commands/, agents/, skills/,
hooks/hooks.json. The only file that changes is the manifest.
Claude lifecycle hook names (PreToolUse, PostToolUse, UserPromptSubmit,
Stop, SessionStart, SessionEnd, Notification) are accepted as aliases, so
a hooks.json written for Claude keeps working — but it must be inlined into
the hooks field. A path to an external hooks file is reported as dropped.
Gemini
gemini-extension.json maps the same way as Matilda: name, version,
description, contextFileName, plus mcpServers when present.
An older .tfcode/plugin manifest
If you have a declarative plugin.json from the agent-plugin system, you do not
need this importer — that format still works exactly as before, and it is gated
by perks.plugins rather than perks.extensions. An extension may contain
one, if you want to distribute it.
For a .ts plugin file, move it into tools/ and wrap it as a plugin factory:
// before: a bare plugin module
export const MyPlugin = async () => ({ tool: { … } })
// after: identical, just placed in tools/my-plugin.ts
export default async () => ({ tool: { … } })
Nothing about the code changes. The location is what makes an extension load it.
After importing
tfcode extension import ./path/to/extension
# review ./path/to/extension/tfcode-extension.json
tfcode extension link ./path/to/extension
tfcode extension approve writing-companion # only if it ships code
Next
- Extension reference — the full field list