Toolfactory

toolfactory

Build an agent tool once; ship it as an Agent Skill, an Agent Plugins bundle, a Claude Code, Codex or Cursor plugin, an MCP server, a CLI, an npm or PyPI package, an MCP Registry entry, an OpenClaw or Hermes native plugin, and a web page, from one operation module and one config file.

toolfactory is a scaffolder and a keeper-in-sync, not a runtime. It writes each surface in the shape that surface's own tooling would have written, proves it with that surface's own validator, and records every generated file in a lock so drift fails CI. Delete toolfactory from a repo it generated and every surface still installs, builds and publishes.

Install

• Agent Skill — npx skills add GoatInAHat/toolfactory
• MCP server — npx -y toolfactory mcp
• Claude Desktop extension — download toolfactory.mcpb from the GitHub Release and double-click to install
• Claude Code plugin — claude plugin marketplace add GoatInAHat/toolfactory, then claude plugin install toolfactory@toolfactory
• Codex plugin — codex plugin marketplace add GoatInAHat/toolfactory, then codex plugin add toolfactory@toolfactory
• Gemini CLI extension — gemini extensions install https://github.com/GoatInAHat/toolfactory
• OpenClaw plugin — openclaw plugins install --link hosts/openclaw from a checkout
• Hermes plugin — hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes
• DSH plugin (experimental) — dsh plugin --profile add ./hosts/dsh from a checkout, or the release tarball toolfactory-dsh-0.4.6.tgz
• Web app — npx -y toolfactory mcp --http --open serves the operations page beside the MCP endpoint on one port and opens it; over MCP or a skill, the web operation does the same and returns the URL.
• npm package — npm install toolfactory

Quickstart

mkdir hello && cd hello

npx toolfactory init --name hello --binding typescript --surfaces skill,agent-plugins,claude,mcp,cli,npm

init writes plugin.json (identity), dev.toolfactory/tool.json (surfaces, binding, config), the kernel scaffold, the .agents/ agent-config canon (skills, MCP servers, sync.py, setup and the per-harness hook carriers, so the tool is developable in any harness), and the first build. It also does what a human would do next: git init and a first commit, then bash .agents/setup, which renders the harness adapters, installs the git hooks that keep them in sync, and installs the dependencies. Its nextSteps end with the one reload line of the harness it is running inside, because reload is the one part a repository cannot automate.

Add --repo / and it creates that GitHub repository through gh and pushes to it — private unless you pass `--public` — with one topic per selected surface, and prepares the live-tests environment when a .env is there. --dryRun prints the gh invocations instead. None of it is required: with no GitHub, plain git or no git at all, everything below still works.

Instruction-only Codex plugin

Use --runtime none --surfaces skill,codex when a plugin is only SKILL.md instructions for Codex. ToolFactory then emits no MCP server, operation snapshot, language scaffold, or consumer runtime dependency. binding remains required for config compatibility but is unused in this mode. This is available in the published npm package starting with ToolFactory 0.1.1.

1. Write operations in src/ops.ts (TypeScript) or src/ /ops.py (Python). Each one is a name, a description, an input schema, an optional output schema, an optional requires list, and a handler.
2. npx toolfactory introspect spawns the kernel MCP server and snapshots tools/list into dev.toolfactory/ops.json.
3. npx toolfactory build regenerates every selected surface in-tree.
4. npx toolfactory gate runs what CI runs, here: build, the drift check, every surface's upstream validator, your own checks and tests, and the credential-free host end-to-end.
5. Commit everything. npx toolfactory package builds the release assets into dist/release/; CI runs the same gate and, on a v* tag, the same package job before publishing.

A TypeScript operation:

operation({

name: "echo", description: "Echo text back.", input: z.object({ text: z.string() }), output: z.object({ text: z.string() }), annotations: { readOnlyHint: true }, handler: async ({ text }) => ({ text }), })

Commands

Every command exists as a CLI subcommand and as an MCP tool (toolfactory mcp), because toolfactory is built with toolfactory.

Surfaces

Skills first. init selects the minimum that already serves every harness — skill, agent-plugins, mcp, cli and the binding's package registry — because everywhere that takes a plugin also takes a skill plus an MCP server, and a skill is one file with no upstream to track. Every host-specific plugin below is opt-in: add it only when that host needs what a skill and an MCP server cannot give it (a gateway tab, browser capability, a store listing).

Select vscode-extension together with mcp, cli, and the runtime registry (npm for TypeScript, pypi for Python). Set vscode.publisher in dev.toolfactory/tool.json, then build. Open hosts/vscode and press F5 to use the checkout's runtime, or run npm run vsix in that directory to package it. Native commands, views, webviews, language services, chat participants, and language-model tools use the full VS Code API in your own src/extension.ts. Add contribution points directly to its package.json; rebuilds preserve author entries and additional fields on generated entries. Marketplace and Open VSX release jobs use VSCE_PAT and OVSX_PAT after you register the publisher. Both can be disabled individually in tool.json.

The same native customization rule applies to the other surfaces: JSON, TOML and YAML manifests merge only projected fields, and host entry points retain your code outside the marked regions. OpenClaw, Herm