Skip to content

FAQ

Jump to bottom
lacause edited this page Mar 29, 2026 · 2 revisions

FAQ & Troubleshooting

General

What is OCC?

OCC (Claude Chain Orchestrator) is a workflow engine that lets you define multi-step AI agent chains in YAML and execute them with automatic parallel processing, dependency resolution, and real-time streaming.

Do I need an Anthropic API key?

No. OCC uses the Claude CLI, which handles authentication. You need Claude CLI installed and authenticated (claude auth login).

What models can I use?

Any model available through Claude CLI: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5. Specify per-step with the model field.

How much does it cost to run?

Depends on your chain. A typical 6-step chain costs ~$0.05-0.15 with Sonnet. See Token Optimization for cost reduction techniques.

Does it work on Windows?

Yes. OCC is cross-platform (macOS, Linux, Windows). CI runs on all three.

Installation

"Claude binary not found in PATH"

The Claude CLI is not installed or not in your PATH.

# Install Claude CLI
npm install -g @anthropic-ai/claude-code

# Verify
which claude    # macOS/Linux
where claude    # Windows

# Or set path explicitly
export CLAUDE_BIN=/path/to/claude

"tsc: command not found"

TypeScript is a dev dependency. Use npx:

cd mcp-server
npm install
npx tsc --noEmit    # Type check
npm run build       # Build

Port 4242 already in use

Change the port:

REST_PORT=8080 npm run rest

Chain Authoring

"Invalid chain: circular dependency"

Your steps have circular depends_on references. Example:

# BAD: A depends on B, B depends on A
- id: a
  depends_on: [b]
- id: b
  depends_on: [a]

Fix: restructure so dependencies form a DAG (directed acyclic graph).

"Missing required input"

Your chain defines required inputs that weren't provided:

inputs:
  - name: topic          # Required (optional: false is the default)
  - name: depth
    optional: true       # This one can be omitted

Provide all required inputs when executing:

curl -X POST http://localhost:4242/execute/my-chain \
  -d '{"input": {"topic": "AI"}}'

My step output is empty

Common causes:

  1. Timeout — step took too long. Increase timeout_ms
  2. Claude error — check the step's error field in the execution result
  3. Wrong variable — check that {variable} names match output_var values
  4. Condition false — step was skipped because its condition evaluated to false

How do I debug a chain?

  1. Check execution status:

    curl http://localhost:4242/executions/{id}

  2. Stream real-time logs:

    curl -N http://localhost:4242/executions/{id}/stream

  3. Look at individual step outputs in the execution result — each step has status, output, error, and durationMs.

Can I use tools in my steps?

Yes. Add the tools field:

- id: analyze
  tools: [Read, Write, Bash, Glob, Grep, WebSearch, WebFetch]
  prompt: "Read and analyze the code at {input.path}"
  output_var: analysis

Execution

"Too many concurrent executions"

Default limit is 5. Wait for running executions to finish, or increase:

MAX_CONCURRENT_EXECUTIONS=10 npm run rest

How do I cancel a running chain?

curl -X DELETE http://localhost:4242/executions/{id}

This kills all active processes and marks pending steps as skipped.

How do I resume a failed chain?

curl -X POST http://localhost:4242/executions/{id}/resume

Completed steps are skipped. Execution resumes from the first non-completed step.

SSE stream disconnects after 60 seconds

OCC sends heartbeat pings every 30s to prevent this. If you're behind a proxy (Nginx, Cloudflare), configure it to allow long-lived connections:

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

MCP

Claude Code doesn't see OCC tools

  1. Check .mcp.json exists in your project root
  2. Verify paths are absolute (not relative)
  3. Restart Claude Code after editing .mcp.json
  4. Check that npm run build was run (needs dist/index.js)

MCP tools error: "CHAINS_DIR does not exist"

The path in .mcp.json → env.CHAINS_DIR doesn't point to a valid directory. Use an absolute path:

"CHAINS_DIR": "/Users/you/projects/OCC/chains"

Performance

Chains are slow

  • Use parallel steps — remove unnecessary depends_on so steps run simultaneously
  • Use cheaper models — claude-haiku-4-5 for simple classification/extraction
  • Enable caching — avoid re-running identical prompts
  • Reduce timeout — set timeout_ms per step instead of waiting 30 min default
  • Use transforms — json_extract instead of asking the LLM to extract

Memory usage is high

  • Reduce MAX_CONCURRENT_EXECUTIONS
  • Set EXECUTION_MAX_AGE_DAYS to a lower value (default: 7)
  • Large step outputs (>1MB) accumulate in memory — use transforms to reduce size

Common Patterns

How do I pass files between steps?

Use pre_tools to read files and tools: [Write] to create them:

- id: generate
  tools: [Write]
  prompt: "Generate code and write to /tmp/output.py"
  output_var: gen_result

- id: review
  depends_on: [generate]
  pre_tools:
    - type: read_file
      path: "/tmp/output.py"
      inject_as: code
  prompt: "Review this code: {code}"
  output_var: review

How do I use environment variables in chains?

pre_tools:
  - type: env_var
    var_name: "DATABASE_URL"
    inject_as: db_url
prompt: "Connect to {db_url} and..."

How do I schedule a chain to run daily?

curl -X POST http://localhost:4242/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Morning briefing",
    "chainName": "smart-briefing",
    "input": {"topic": "tech news"},
    "cron": "0 8 * * *",
    "enabled": true
  }'

See Also

Clone this wiki locally