---
title: Claude Code
description: Run Smithers from Anthropic's Claude Code. Sync generated skill files, register the MCP server, or drop in the Claude Code plugin that bundles both.
---

[Claude Code](https://code.claude.com/docs) extends through **skills**, **MCP
servers**, and **plugins**. Smithers ships into all three. The fastest path is:

```bash
bunx smithers-orchestrator skills add
bunx smithers-orchestrator mcp add --agent claude-code
```

That syncs generated Smithers CLI skill files to Claude's supported skill
location and registers the MCP server in `~/.claude.json`. Restart Claude Code
(or run `/mcp`) and it can list, run, watch, and approve workflows.

## Curated onboarding skill

The onboarding skill teaches Claude the Smithers mental model and ships the full
docs bundle next to it. `init` installs it automatically when Claude Code is
detected:

```bash
bunx smithers-orchestrator init
```

Claude loads a skill when its `description` matches the request, so once it's
installed you just ask for the outcome, *"orchestrate an agent to add rate
limiting and keep iterating until the tests pass"*, and Claude reaches for
Smithers itself.

## Generated CLI skills

`skills add` syncs generated skill files for Smithers CLI command groups:

```bash
bunx smithers-orchestrator skills add
```

For project-scoped generated skill files, pass `--no-global`.

## Register the MCP server

`mcp add` writes the registration for you. To do it by hand, add a server with
the Claude CLI:

```bash
claude mcp add --transport stdio --scope user smithers \
  -- bunx smithers-orchestrator --mcp
```

Or commit a project-scoped `.mcp.json` so the whole team gets it:

```json
{
  "mcpServers": {
    "smithers": {
      "command": "bunx",
      "args": ["smithers-orchestrator", "--mcp"]
    }
  }
}
```

The server exposes the semantic tool surface: `list_workflows`, `run_workflow`,
`watch_run`, `list_pending_approvals`, `resolve_approval`, `explain_run`, and
more. See the [MCP Server reference](/integrations/mcp-server) for every tool.

## Claude Code plugin

A plugin bundles the skill and MCP server behind a single install, namespaced as
`smithers:`. The manifest lives at `.claude-plugin/plugin.json`:

```json
{
  "name": "smithers",
  "version": "0.2.0",
  "description": "Durable control plane for long-running coding agents"
}
```

The MCP server is wired through a sibling `.claude-plugin/.mcp.json`, and the
skill is auto-discovered from the plugin's `skills/` directory, so neither is
declared inside `plugin.json` itself.

Install from a marketplace and reload without restarting:

```
/plugin marketplace add smithersai/smithers
/plugin install smithers@smithersai
/reload-plugins
```

See the worked examples: [plugin (skill)](/examples/claude-plugin-skill) and
[plugin (orchestrator)](/examples/claude-plugin-orchestrator).

## Standing instructions

Add a line to `CLAUDE.md` so Claude remembers Smithers is the tool for durable,
multi-step work:

```md
## Orchestration
For multi-step, long-running, or human-in-the-loop agent work, use Smithers:
`bunx smithers-orchestrator starters` lists ready-made workflows.
```

## Smithers runs Claude Code too

In the other direction, Smithers spawns Claude Code as a worker inside a
workflow via `ClaudeCodeAgent`, with native session hijack:

```tsx
import { ClaudeCodeAgent } from "smithers-orchestrator";

const claude = new ClaudeCodeAgent({ model: "claude-fable-5" });
```

By default this bills your Claude Pro/Max subscription: `ClaudeCodeAgent` clears
`ANTHROPIC_API_KEY` from the spawned process so the CLI uses subscription auth,
no API key required. To run multiple subscriptions side by side, set one up with
`CLAUDE_CONFIG_DIR=<dir> claude` plus `/login`, then pass `configDir: "<dir>"`.
Passing `apiKey` switches that invocation to Anthropic API billing.

You can also call it once for a typed completion with no graph:

```ts
const { output } = await claude.generate({
  prompt: 'Reply with JSON: {"ok": true}',
  outputSchema: z.object({ ok: z.boolean() }),
  timeout: { totalMs: 60_000, idleMs: 30_000 },
});
```

See [CLI Agents → Claude Code](/integrations/cli-agents#claude-code-cli-agent)
and [Subscription-mode structured completion](/integrations/cli-agents#subscription-mode-structured-completion).
