YClaw Agent Orchestrator (AO)

When YClaw agents need to write code, they don't hallucinate file contents into chat. They delegate to the Agent Orchestrator — a sidecar service that spins up real coding agent sessions in isolated workspaces with full filesystem access, test runners, and git.

Two Paths to Code

codegen:direct — API-Only

For straightforward changes where the agent already knows what to write:

• Commits files directly via GitHub API
• Opens PR with full content
• No subprocess, no workspace, no clone
• Fast, cheap, deterministic

codegen:execute — Full Coding Session

For complex tasks requiring exploration, iteration, and testing:

• Provisions an isolated workspace (clone → branch → install deps)
• Spawns a coding agent harness
• Agent explores codebase, writes code, runs tests
• Fix-test loop up to N iterations
• Pushes branch + opens PR on completion

Workspace Provisioning

Every codegen:execute session gets a clean, isolated workspace:

/app/tmp/codegen/ws-{uuid}/
├── repo/           ← git clone of target repo
│   ├── CLAUDE.md   ← auto-generated context (ephemeral, gitignored)
│   ├── codex.md    ← same context, Codex format
│   ├── opencode.json
│   └── ...         ← the actual codebase
└── output/         ← session artifacts, logs

The Provisioner composes context files from:

• Repo-specific rules and conventions
• Session context (issue description, PR history, linked discussions)
• Bundled meta-skills (coding patterns, testing standards)
• Safety rules (path restrictions, secret scanning)

Every coding session starts with full project context regardless of which harness runs it.

Coding Agent Harnesses

AO supports 5 coding agent backends. The BackendRouter selects the best available, with automatic fallback through the chain: claude → codex → opencode.

Harness Overview

Claude Code (Default)

The default harness. Runs Anthropic's coding agent in non-interactive mode.

claude -p <task> --output-format json --max-turns 25

• Strongest reasoning for complex multi-file changes
• Handles ambiguous specs well ("figure out how to fix this test")
• Structured JSON output for reliable result parsing
• Higher cost per session, fewer iterations needed

Codex

OpenAI's coding agent CLI. Good alternative when Anthropic is unavailable or for GPT-native codebases.

codex --task <task> --mode auto

• Fast for well-specified, explicit instructions
• Lower cost per token
• Falls back automatically if Claude Code is unavailable

Pi (SDK Mode)

pi-coding-agent integrated directly via SDK — no CLI subprocess spawning.

• Persistent sessions — conversation history preserved across turns
• Multi-turn steering — send follow-up instructions ("try a different approach", "also fix the types")
• Reattachable — sessions survive worker restarts
• Custom sandboxed tools — YClaw provides its own read, write, edit, ls, grep, bash with path restrictions and secret redaction. Built-in tools disabled (deny-by-default)
• Any model — works with Anthropic, OpenRouter, or local Ollama
• Best for iterative work that needs back-and-forth

OpenCode / Gemini CLI

Community and alternative backends. Same provisioning pipeline, different execution engine. Useful for model diversity or cost optimization.

Backend Selection

Repo config: preferred_backend (default: "claude")
    ↓
BackendRouter checks: API key set? CLI installed?
    ↓
Available → use it
Unavailable → fallback: claude → codex → opencode
    ↓
All unavailable → codegen:execute fails gracefully

Per-repo configuration in repos/*.yaml:

preferred_backend: claude    # or codex, opencode

Global default in yclaw.config.yaml:

defaultHarness: claude-code  # claude-code | codex | opencode | gemini-cli | pi

AO ↔ YClaw Integration

YClaw Core (agents, EventBus, triggers)
    │
    │  codegen:execute or codegen:direct
    ↓
Agent Orchestrator (AO)
    │
    ├── WorkspaceProvisioner
    │     clone → branch → inject CLAUDE.md/codex.md → install deps
    │
    ├── BackendRouter
    │     select harness → check availability → fallback chain
    │
    ├── CodingExecutor (run session)
    │     ├── ClaudeCodeBackend
    │     ├── CodexBackend
    │     ├── PiCodingExecutor
    │     ├── OpenCodeBackend
    │     └── GeminiCliBackend
    │
    ├── SecretScanner (pre-push)
    │     scan all changed files before pushing to GitHub
    │
    └── Webhook Notifier → YClaw Core
          ├── urgent  — agent stuck, errored
          ├── action  — PR ready to merge
          ├── warning — auto-fix failed
          └── info    — session complete

Reactions (Post-Session)

AO feeds results back to YClaw's reaction engine:

Configuration

AO Config (ao/agent-orchestrator.yaml)

dataDir: /data/ao-state              # Session metadata (EBS-backed)
worktreeDir: /data/worktrees         # Git worktrees
port: 3001                           # Dashboard (avoids conflict with core)

defaults:
  runtime: process                   # Subprocess mode (headless, no TTY)
  agent: claude-code                 # Default harness
  workspace: worktree                # Git worktree isolation
  notifiers: [webhook]               # Callback to YClaw core

projects:
  my-project:
    repo: your-org/my-repo
    defaultBranch: main
    agentConfig:
      permissions: permissionless    # No human approval for code changes
    scm:
      plugin: github
    tracker:
      plugin: github

Required Environment Variables

Deployment

docker-compose up
├── yclaw-core     ← Agents, EventBus, executor
├── yclaw-ao       ← Agent Orchestrator
├── mongodb        ← State, task tracking
├── redis          ← Cache, rate limiting
└── litellm        ← LLM proxy, cost tracking

Production (ECS Fargate): AO runs as a separate task with an EBS volume for persistent workspaces. Secrets via AWS Secrets Manager.