Skip to content

claude-code.md

Latest commit

 

History

History
129 lines (91 loc) · 4.44 KB

claude-code.md

File metadata and controls

129 lines (91 loc) · 4.44 KB

Running Ouroboros with Claude Code

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)
  • Python >= 3.12
  • Ouroboros installed (see Getting Started for install options)

The [claude] extra (pip install ouroboros-ai[claude]) installs claude-agent-sdk and anthropic -- required for Claude Code runtime integration. The base ouroboros-ai package does not include these.

Configuration

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

orchestrator:
  runtime_backend: 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 orchestrator uses claude-agent-sdk which connects directly to your authenticated Claude Code session. No API key required. 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 ~/.ouroboros/ouroboros.db.

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.