Running Ouroboros with Claude Code

한국어: claude-code.ko.md

Ouroboros can use Claude Code as a runtime backend, leveraging your Claude Code Pro or Max Plan subscription to execute workflows without requiring a separate API key.

For installation and first-run onboarding, see Getting Started.

Command context guide: This page contains commands for two different contexts:

• Terminal -- commands you run in your regular shell (bash, zsh, etc.)
• Inside Claude Code session -- ooo skill commands that only work inside an active Claude Code session (start one with claude)

Each code block is labeled to indicate where to run it.

Prerequisites

• Claude Code CLI installed and authenticated (Pro or Max Plan)
• uv if you use the marketplace plugin. The plugin's MCP manifest launches the server with the bundled uvx command (.claude-plugin/.mcp.json), so a host with only Claude Code cannot start it. Install uv with pipx install uv, pip install --user uv, or brew install uv.
• No global Python is required for the marketplace plugin. Its shipped skills resolve Python >= 3.12 in this order: compatible python3, compatible python, then uv run --no-project --quiet --python '>=3.12' python. This rejects older host interpreters and lets the same uv prerequisite cover the first-run welcome, setup, and seed snippets.
• Python >= 3.12 specifically, for the standalone CLI.
• Ouroboros installed, for the standalone CLI (see Getting Started for install options)

Install ouroboros-ai[claude] for the default in-process SDK runtime on MCP 1.x. The marketplace plugin launches the MCP 2 server from an isolated ouroboros-ai[mcp] environment and selects the [claude-cli] worker. Never combine [mcp] with [claude], [claude-sdk], or [all] in one interpreter.

Configuration

To select Claude Code as the runtime backend, set the following in your Ouroboros configuration:

orchestrator:
  runtime_backend: claude  # written by `ouroboros setup --runtime claude`

When using the --orchestrator CLI flag, Claude Code is the default runtime backend.

How It Works

+-----------------+     +------------------+     +-----------------+
|   Seed YAML     | --> |   Orchestrator   | --> |  Claude Code    |
|  (your task)    |     |   (adapter.py)   |     |  (Pro/Max Plan) |
+-----------------+     +------------------+     +-----------------+
                                |
                                v
                        +------------------+
                        |  Tools Available |
                        |  - Read          |
                        |  - Write         |
                        |  - Edit          |
                        |  - Bash          |
                        |  - Glob          |
                        |  - Grep          |
                        +------------------+

The default profile uses the Agent SDK and its bundled/authenticated Claude Code transport. The SDK remains on MCP 1.x. The plugin-owned MCP 2 server is a separate uvx process and uses --runtime claude-cli, so no interpreter loads both MCP majors. For LiteLLM consensus models, see credentials.yaml.

For a side-by-side comparison of all runtime backends, see the runtime capability matrix.

Claude Code-Specific Strengths

• Zero API key management -- uses your Pro or Max Plan subscription directly
• Rich tool access -- full suite of file, shell, and search tools via Claude Code
• Session continuity -- resume interrupted workflows with --resume

CLI Options

All commands in this section run in your regular terminal (shell), not inside a Claude Code session.

Interview Commands

Terminal:

# Start interactive interview (Claude Code runtime)
uv run ouroboros init start --orchestrator "Your idea here"

# Resume an interrupted interview
uv run ouroboros init start --resume interview_20260127_120000

# List all interviews
uv run ouroboros init list

Workflow Commands

Terminal:

# Execute workflow (Claude Code runtime)
uv run ouroboros run workflow --orchestrator seed.yaml

# Dry run (validate seed without executing)
uv run ouroboros run workflow --dry-run seed.yaml

# Debug output (show logs and agent thinking)
uv run ouroboros run workflow --orchestrator --debug seed.yaml

# Resume a previous session
uv run ouroboros run workflow --orchestrator --resume <session_id> seed.yaml

Troubleshooting

"Providers: warning" in health check

This is normal when not using LiteLLM providers. The orchestrator mode uses Claude Code directly.

Session fails with empty error

Ensure you're running from the project directory:

Terminal:

cd /path/to/ouroboros
uv run ouroboros run workflow --orchestrator seed.yaml

"EventStore not initialized"

The database will be created automatically at the active path shown by ouroboros config show.

Cost

Using Claude Code as the runtime backend with a Pro or Max Plan means:

• No additional API costs -- uses your subscription
• Execution time varies by task complexity
• Typical simple tasks: 15-30 seconds
• Complex multi-file tasks: 1-3 minutes

Note: Pro plan ($20/month) works but has lower usage limits. For long agentic workflows, Max plan is recommended to avoid hitting limits mid-session.

Active Conductor and Synapse

Claude Agent SDK and persisted Claude worker sessions are proven Synapse inform/after_turn transports. Delivery resumes the same native session only after the current turn; resumability is not presented as live checkpoint redirect, and hard replace remains unsupported.

The main Claude conversation delegates exactly one read-only observer, stays available to the user, and relays current runtime/model, efficiency assurance, bounded Discover targets, dependency/parallel levels, first scheduled ACs, attention, and terminal assurance. It chooses an AC semantically without asking for internal IDs. Guidance is canonical English; the host responds naturally in the user's current conversation language.