Skip to main content
Smithers is driven by an agent, not clicked by a human. You ask your coding agent for an outcome, “implement rate limiting and keep iterating until the tests pass”, and it reaches for Smithers, starts the workflow, watches it, and clears approvals on your behalf. These pages cover how to wire Smithers into each agent so it can do that.
Just want to get running? Set up in your harness is the two-minute version, with a copy-paste prompt that has your agent install Smithers for you.
There are three integration surfaces. Most agents support more than one; pick the one that matches how the agent is extended.

​
Two commands cover most setup

The Smithers CLI can sync Smithers skill files where supported and register the MCP server into detected coding agents, no per-agent config by hand.
Target a single MCP agent with --agent, or scope skill installs to the current project with --no-global:
skills add generates a skill per CLI command group (bunx smthrs up, bunx smthrs ps, bunx smthrs approve, …) and syncs them into supported skill locations, including the canonical ~/.agents/skills directory. mcp add registers bunx smthrs --mcp in each agent’s MCP config. Override the launch command with --command if Smithers is a project dependency.
If mcp add exits with MCP_ADD_FAILED and unknown option '--mcp', the underlying registration helper word-split the launch command and parsed --mcp as one of its own flags. Register with the agent’s own CLI instead, with a -- separator so the agent passes --mcp through to Smithers untouched:
The CLI prints these commands for you when mcp add fails. See MCP Server → If mcp add fails for the hand-written config.

​
The onboarding skill

The two commands above expose the CLI. The curated smithers onboarding skill goes further. It teaches the agent the mental model (Smithers as durable plan mode, the .smithers/ layout, which component to reach for) and ships the full docs bundle next to it so the agent can read the exact API on demand. init installs the curated onboarding skill automatically for detected agents whose skill directory Smithers can write directly today: Claude Code and Pi. skills add is the one command that makes every Smithers-owned skill current: it syncs the generated CLI command skills and the curated smithers skill (SKILL.md plus the llms-full.txt bundle) from the installed package.
It behaves identically in an agent, a CI job, and an interactive terminal, so a non-interactive session is never left on the previous release’s curated skill. Its success output names both halves of what it synced. skills list reports the curated skill’s status and version next to the command skills, and flags a stale copy:
bunx smthrs update runs the same sync once the package upgrade finishes, so an upgrade leaves every Smithers-owned skill current on its own. Opt out of the curated-skill half with SMITHERS_NO_SKILL_REFRESH=1. skills add supports --no-global for project-scoped installs; unlike mcp add, it has no supported --agent target filter. See each agent’s page for the exact supported setup.

​
Support matrix

mcp add also reaches Gemini CLI, OpenCode, Amp, Windsurf, Cline, Continue, Roo, Kilo, Goose, Augment, Trae, Junie, Crush, Kiro, Qwen Code, OpenHands. Run it once and any detected MCP-capable agent is wired up.
Pi, Hermes, and OpenClaw aren’t in the underlying skill/MCP framework’s built-in registry, so Smithers wires them as a supplementary step: mcp add writes the Smithers server into Hermes’s config.yaml and OpenClaw’s openclaw.json, also installing the native Hermes/OpenClaw plugin where supported. skills add copies the canonical skill set into Pi’s ~/.pi/agent/skills. MCP wiring respects --agent and --command; skill wiring respects --no-global. Each preserves existing config and silently skips an agent that isn’t installed.

​
Worker defaults: Claude builds and gates, Codex checks

When bunx smthrs init finds usable Codex authentication, the generated implementation pool starts with Claude Opus 5, the checking pools start with Codex, and every pool pins the model tier to the job: Start substantial implementation on Claude Opus 5 (registry v7: it outbenchmarks GPT-5.6 Sol on agentic coding at lower output cost) and escalate to Fable 5 for the most ambitious builds; Sol reviews, Terra validates, and Luna stays on trivial, minimal-risk work only. Orchestration and gating never go to GPT-5.6 Sol or Terra: deciding scope, choosing direction, judging progress, and calling work done are Claude seats (Opus 5 at medium reasoning effort, Fable 5 for planning), with Codex Sol only as an availability fallback. Smithers uses the exact tier IDs above, not the floating gpt-5.6 alias. See SOTA role defaults. Kimi, Gemini, and the other adapters remain supported as later entries in the runtime failover chain; they engage only after the earlier agents cannot complete the task. A workflow that explicitly constructs one of those provider-specific agents continues to use it as written.

​
The other direction: Smithers runs the agent

Everything above is about an agent driving Smithers. Smithers also runs these agents as the workers inside a workflow. <Task agent={codex}> spawns Codex, <Task agent={claude}> spawns Claude Code, <Task agent={cursor}> spawns cursor-agent, and so on. Native session hijack is available where the adapter supports it. That’s covered in CLI Agents and SDK Agents.

​
See also