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.mcpbfrom the GitHub Release and double-click to install - Claude Code plugin —
claude plugin marketplace add GoatInAHat/toolfactory, thenclaude plugin install toolfactory@toolfactory - Codex plugin —
codex plugin marketplace add GoatInAHat/toolfactory, thencodex plugin add toolfactory@toolfactory - Gemini CLI extension —
gemini extensions install https://github.com/GoatInAHat/toolfactory - OpenClaw plugin —
openclaw plugins install --link hosts/openclawfrom a checkout - Hermes plugin —
hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes - DSH plugin (experimental) —
dsh plugin --profile <profile> add ./hosts/dshfrom a checkout, or the release tarballtoolfactory-dsh-0.4.6.tgz - Web app —
npx -y toolfactory mcp --http --openserves the operations page beside the MCP endpoint on one port and opens it; over MCP or a skill, theweboperation 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 <owner>/<name> 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.
- Write operations in
src/ops.ts(TypeScript) orsrc/<pkg>/ops.py(Python). Each one is a name, a description, an input schema, an optional output schema, an optionalrequireslist, and a handler. npx toolfactory introspectspawns the kernel MCP server and snapshotstools/listintodev.toolfactory/ops.json.npx toolfactory buildregenerates every selected surface in-tree.npx toolfactory gateruns 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.- Commit everything.
npx toolfactory packagebuilds the release assets intodist/release/; CI runs the same gate and, on av*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, Hermes, DSH and browser shims can use their host's complete native API. adopt and
eject remain available when replacing a generated integration entirely.
Package distribution is opt-in. PyPI supports both pip install and uv add; pip uses the same
published wheel/sdist. Other ecosystems consume real native packages and metadata supplied by the
author. See native package releases and
system package releases for configuration and registry setup.
Toolfactory itself continues to use npm as its package registry.
Driving toolfactory from an agent
Selecting both skill and openclaw-native ships the tool's own skill with the native plugin
by default. openclaw.skills is an exact override: [] opts out; ["my-tool", "custom"]
ships the generated own skill and .agents/skills/custom/. An explicit custom-only list
continues to ship only those skills. The own skill's generated regions are refreshed in the
same build; authored prose and UTF-8 text resources are retained. The native manifest declares
skills: ["./skills"], and npm packaging includes that directory. No native plugin skill is
inferred when the standalone skill surface is absent.
Every command is an MCP tool, so a host can drive the whole loop without a shell — and nothing is
registered by hand. Every generated project carries the .agents/ canon, so toolfactory and the
tool's own kernel are already entries in .agents/mcp/servers.json, which bash .agents/setup
renders into whichever harnesses are on the machine (.mcp.json, .cursor/mcp.json,
.codex/config.toml, …) and keeps in sync from every one of them. root is an argument of every
tool, so one registration serves every repository on the machine; from inside a host worktree,
pass it explicitly.
Reload is the one part a repository cannot automate, so init prints the line that matches the
harness it is running inside, and the generated AGENTS.md carries the table it comes from.
Inside OpenClaw, install the tool you are building with
openclaw plugins install --link <repo>/hosts/openclaw --force; inside Hermes, commit and run
hermes plugins install file://<repo>#hosts/hermes/<pkg> — every hermes run is a fresh process,
and hermes gateway restart is only for the messaging gateway.
GSD uses the same skills, CLI and MCP server; no GSD-specific surface is needed. From a generated
project, run bash .agents/setup --all so .mcp.json is rendered even on a GSD-only machine,
then discover its server in an interactive GSD session before unattended use. GSD launched by
OpenClaw or Hermes loads the child project's configuration separately from the outer agent.
See GSD compatibility for setup, runtime boundaries and the repeatable smoke test.
The boundary
Core logic is a pure function of JSON arguments, environment/config and the filesystem. An
operation declares what it needs from a closed vocabulary: net, fs, shell, secret are
portable; browser, model, user-input, channel are not. Every surface gets a per-operation
verdict (native, bridged, degraded, excluded, with a reason) in COVERAGE.md, and an
excluded operation is left off that surface's tool list rather than stubbed. A tool that needs a
browser is written as two operations: one that takes the page content as an argument and runs
everywhere, and one that declares browser and runs only where a browser exists.
See docs/spec.md for the normative design.
Repository
toolfactory's own repo is generated by toolfactory build from its dev.toolfactory/tool.json.
pnpm check, pnpm test, pnpm toolfactory check and pnpm toolfactory validate are the gates.
