Recursive Agent Container -- Composable Unix processes for orchestrating LLM CLI tools
CSA is a headless IDE runtime for AI agents. It provides a unified CLI that orchestrates multiple AI coding tools (claude-code, codex, gemini-cli, opencode) as composable Unix processes -- enabling recursive sub-agent spawning, model-heterogeneous code review, and resource-aware scheduling.
Built-in sub-agents and agent-teams are homogeneous -- they only use one model family. Reviews suffer from same-model blind spots. CSA enforces heterogeneous execution: if the parent is Claude, the reviewer is automatically Codex or Gemini, and vice versa. No silent fallback.
| Feature | Description |
|---|---|
| Recursive Agents | Any agent can spawn sub-agents via csa run, up to configurable depth (default: 5) |
| Heterogeneous Review | csa review and csa debate auto-select a different model family than the caller |
| ACP Transport | Precise context injection via Agent Communication Protocol, replacing 60K+ token auto-load |
| MCP Hub | Shared MCP server fan-out daemon with FIFO queuing and stateful pooling |
| Resource Sandbox | Three-layer defense: cgroup v2, setrlimit, RSS monitor -- with P95 memory estimation |
| Session Persistence | ULID-based sessions with genealogy, checkpoints (git-notes), and prefix matching |
| Skill-as-Agent | Skills package complete agent definitions (prompt + tools + protocol) |
| Weave Compiler | skill-lang patterns compile to deterministic workflow plans (workflow.toml) |
| Consensus Engine | Multi-reviewer with majority / unanimous / weighted strategies |
| Config-Driven | Tool selection and thinking budget from tiered config; CLI flags are overrides |
# Install via mise (recommended -- no Rust toolchain needed)
mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=csa]
mise use -g ubi:RyderFreeman4Logos/cli-sub-agent[exe=weave]
# Or install via script
curl -fsSL https://raw.githubusercontent.com/RyderFreeman4Logos/cli-sub-agent/main/install.sh | sh
# Initialize a project
cd my-project && csa init && csa doctor
# Run a task
csa run "implement user auth module"
# Code review (auto-selects heterogeneous model)
csa review --diff
# Adversarial debate
csa debate "Should we use Redis or Memcached for caching?"See Getting Started for full installation and setup instructions.
Main Agent (depth=0, claude-code)
|-- Reviewer (depth=1, codex) # heterogeneous review
| +-- Analyzer (depth=2, gemini) # deep analysis
+-- Debater (depth=1, codex) # adversarial debate
+-- Adversary (depth=2, claude) # counter-argument
CSA is organized as 14 workspace crates:
| Crate | Purpose |
|---|---|
cli-sub-agent |
Main CLI binary (csa) |
csa-core |
Core types (ToolName, ULID, OutputFormat) |
csa-acp |
ACP transport (AcpConnection, AcpSession) |
csa-session |
Session CRUD, genealogy, transcripts |
csa-executor |
Tool executor (closed enum, Transport trait) |
csa-process |
Process spawning, signals, sandbox integration |
csa-config |
Global + project config merging, migrations |
csa-resource |
Memory estimation, cgroup/rlimit sandbox |
csa-scheduler |
Tier rotation, 429 failover, concurrency slots |
csa-mcp-hub |
MCP server fan-out daemon |
csa-hooks |
Lifecycle hooks and prompt guards |
csa-todo |
Git-tracked TODO/plan management |
csa-lock |
flock-based session and slot locking |
weave |
skill-lang compiler (weave binary) |
See Architecture for design principles and dependency graph.
| Tool | Provider | Transport | Context |
|---|---|---|---|
| claude-code | Anthropic | ACP | 200K |
| codex | OpenAI | ACP | 200K |
| gemini-cli | Legacy CLI | 2M | |
| opencode | OpenRouter | Legacy CLI | 200K |
| Chapter | Description |
|---|---|
| Getting Started | Installation, first run, project setup |
| Architecture | Crate structure, design principles, data flow |
| Commands | Complete CLI reference with flags and examples |
| Configuration | Global/project config, tiers, aliases |
| Sessions | Session lifecycle, genealogy, checkpoints |
| ACP Transport | Agent Communication Protocol, context injection |
| MCP Hub | Shared MCP daemon, proxy injection, FIFO queue |
| Resource Control | Sandbox, cgroup, rlimits, P95 estimation |
| Skills & Patterns | Skill system, weave compiler, workflow.toml |
| Hooks | Lifecycle hooks and prompt guards |
| Debate & Review | Heterogeneous review, consensus engine |
| MCP Hub on macOS | launchd integration guide |
# Requirements: Rust 1.85+, just
just clippy # Build + lint
just test # Run tests
just fmt # Format
just pre-commit # Full pre-commit checkApache-2.0