Skip to main content
Version: v3

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​