> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Support

> Connect Smithers to the coding agent you already use (Codex, Claude Code, Cursor, Copilot, Pi, Hermes, OpenClaw, and more) so the agent can run, watch, and steer workflows for you.

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.

<Note>
  Just want to get running? [Set up in your harness](/agents/setup) is the
  two-minute version, with a copy-paste prompt that has your agent install Smithers
  for you.
</Note>

There are three integration surfaces. Most agents support more than one; pick the
one that matches how the agent is extended.

| Surface          | What it gives the agent                                                                                           | Ship it with                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **Skill**        | Agent-facing Smithers context, either curated onboarding where directly supported or generated CLI command skills | `init` / `skills add`          |
| **MCP server**   | Structured tools to list, run, watch, inspect, and control runs without shell-parsing                             | `mcp add` or native MCP config |
| **Instructions** | A standing note in `AGENTS.md` / `CLAUDE.md` so the agent knows Smithers is available                             | a few lines in the repo        |

## 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Sync the Smithers skill set into supported skill locations
bunx smithers-orchestrator skills add

# Register Smithers as an MCP server in every detected agent
bunx smithers-orchestrator mcp add
```

Target a single MCP agent with `--agent`, or scope skill installs to the current
project with `--no-global`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator mcp add --agent cursor
bunx smithers-orchestrator skills add --no-global   # writes .agents/skills in the repo
```

<Note>
  `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.
</Note>

<Warning>
  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:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  codex mcp add smithers -- bunx smithers-orchestrator --mcp
  claude mcp add smithers -- bunx smithers-orchestrator --mcp
  ```

  The CLI prints these commands for you when `mcp add` fails. See
  [MCP Server → If `mcp add` fails](/integrations/mcp-server#if-mcp-add-fails) for
  the hand-written config.
</Warning>

## 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator skills add
```

`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

| Agent                              | Skill                                                               | MCP server                                                | Notes                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [Codex](/agents/codex)             | Use `docs-full` / `ask`; no automatic skill install                 | `mcp add` / `config.toml` (TOML)                          | `AGENTS.md` for standing instructions                                                                 |
| [Claude Code](/agents/claude-code) | `skills add`                                                        | `mcp add` → `~/.claude.json`                              | Also a Claude Code **plugin** (skill + MCP bundled)                                                   |
| [Cursor](/agents/cursor)           | Optional `skills add` → `~/.agents/skills` if bridged               | `mcp add` / `.cursor/mcp.json`                            | Rules in `.cursor/rules/*.mdc`; `cursor-agent` CLI                                                    |
| [GitHub Copilot](/agents/copilot)  | Custom instructions / prompt files                                  | `.vscode/mcp.json` (editor) / repo settings (cloud agent) | Two distinct MCP schemas                                                                              |
| [Pi](/agents/pi)                   | `skills add` → `~/.pi/agent/skills`                                 | no native MCP                                             | First-party `pi-plugin` with a live run inspector; see [Pi integration](/integrations/pi-integration) |
| [Hermes](/agents/hermes)           | `skills add`                                                        | `mcp add` → `~/.hermes/config.yaml` (YAML)                | Reads `AGENTS.md`                                                                                     |
| [OpenClaw](/agents/openclaw)       | Native Smithers plugin + optional `skills add` → `~/.agents/skills` | `mcp add` → `~/.openclaw/openclaw.json`                   | `mcp add --agent openclaw` installs the plugin and MCP entry                                          |

`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.

<Note>
  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.
</Note>

## 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:

| Work                                                                                      | Default model   |
| ----------------------------------------------------------------------------------------- | --------------- |
| Planning, orchestration, review, and the hardest reasoning                                | `gpt-5.6-sol`   |
| Mid-tier judgment, validation, or tool-heavy work that needs extra checking               | `gpt-5.6-terra` |
| **Research, implementation, ordinary tool use, UI, and routine-to-substantial execution** | `gpt-5.6-luna`  |

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](/reference/sota-models#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](/integrations/cli-agents) and
[SDK Agents](/integrations/sdk-agents).

## See also

* [MCP Server](/integrations/mcp-server): the full semantic tool reference
* [Installation](/installation): the workflow pack and the onboarding skill
* [Integrations](/integrations/integrations): connecting Smithers to external services