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 smithers-orchestrator up, bunx smithers-orchestrator ps, bunx smithers-orchestrator approve, …) and syncs them into supported skill locations, including the canonical ~/.agents/skills directory. mcp add registers bunx smithers-orchestrator --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. To sync the generated Smithers CLI skill set at any time:
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.

​
Codex-first worker defaults

When bunx smithers-orchestrator init finds usable Codex authentication, every generated workflow pool starts with Codex and pins the model tier to the job: Start with Luna for most work, including substantial implementation and ordinary tool use; size alone does not promote a task to Sol. Escalate to Terra for stronger validation or structured tool-heavy judgment, and to Sol for ambiguity, high-stakes decisions, novel architecture, orchestration, final review, or repeated failure. Smithers uses the exact tier IDs above, not the floating gpt-5.6 alias. See SOTA role defaults. Claude Code, Kimi, Gemini, and the other adapters remain supported as later entries in the runtime failover chain. A healthy Codex attempt completes before they can run; they engage only after Codex 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={openclaw}> spawns OpenClaw, and so on. Native session hijack is available where the adapter supports it. That’s covered in CLI Agents and SDK Agents.

​
See also