> ## Documentation Index
> Fetch the complete documentation index at: https://smithers-feat-claude-workflow-mirror.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Support

> Connect Smithers to the coding agent you already use (Claude Code, Codex, Cursor, Copilot, Pi, Hermes, OpenClaw, and ~20 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**        | Fluency in Smithers (when to use it, the CLI verbs, the component catalog) loaded on demand | `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 agents

The Smithers CLI installs both the skill and the MCP server into every coding
agent it detects on your machine, no per-agent config by hand.

```bash theme={null}
# Install the Smithers skill set into every detected agent
# (Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode, Amp, Windsurf, …)
bunx smithers-orchestrator skills add

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

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

```bash theme={null}
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 installs them to the canonical `~/.agents/skills`
  directory, symlinking into each agent that uses its own path (Claude Code →
  `~/.claude/skills`, Windsurf → `~/.codeium/windsurf/skills`, …). `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={null}
  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 skill automatically for every detected agent. To install or
re-install at any time:

```bash theme={null}
bunx smithers-orchestrator skills add
```

Target a single agent with `--agent` (e.g. `--agent codex`, `--agent cursor`).
See each agent's page for the exact path where the skill lands.

## Support matrix

| Agent                              | Skill                               | MCP server                                                | Notes                                                                                                 |
| ---------------------------------- | ----------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [Claude Code](/agents/claude-code) | `skills add`                        | `mcp add` → `~/.claude.json`                              | Also a Claude Code **plugin** (skill + MCP bundled)                                                   |
| [Codex](/agents/codex)             | `skills add` → `~/.codex/skills`    | `mcp add` / `config.toml` (TOML)                          | `AGENTS.md` for standing instructions                                                                 |
| [Cursor](/agents/cursor)           | `skills add` → `~/.cursor/skills`   | `mcp add` / `.cursor/mcp.json`                            | Rules in `.cursor/rules/*.mdc`; `cursor-agent` CLI                                                    |
| [GitHub Copilot](/agents/copilot)  | `skills add` → `~/.copilot/skills`  | `.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)       | `skills add` → `~/.agents/skills`   | `mcp add` → `~/.openclaw/openclaw.json`                   | Skills via ClawHub                                                                                    |

`skills add` and `mcp add` also reach **Gemini CLI, OpenCode, Amp, Windsurf,
Cline, Continue, Roo, Kilo, Goose, Augment, Trae, Junie, Crush, Kiro, Qwen Code,
OpenHands**. Run them once and any detected 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`
  directly, and `skills add` copies the canonical skill set into Pi's
  `~/.pi/agent/skills`. Each respects `--no-global`, `--agent`, and `--command`,
  preserves existing config, and silently skips an agent that isn't installed.
</Note>

## 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={claude}>` spawns
Claude Code, `<Task agent={codex}>` spawns Codex, and so on, with native session
hijack to take over interactively. 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