Silent infrastructure for AI orchestration.
Hierarchical multi-agent system that turns directives into engineering outcomes.

For AI Agents · For Humans · How It Works · Installation · Docs

Silent infrastructure that "just works" — Echelon is designed for AI-to-AI orchestration. Your AI assistant (Claude Code, Cursor, etc.) delegates complex work to Echelon's management hierarchy, monitors progress, and reports back. You never need to run echelon directly.

Give a directive through your AI assistant. Echelon builds the team, plans the work, creates GitHub issues, writes the code, and opens PRs.

Human
  ↓ "Build JWT auth with refresh tokens"
AI Assistant (Claude Code)
  ↓ delegates to Echelon
Echelon Organization
  ├─ 2IC          → breaks directive into workstreams
  ├─ Eng Lead     → designs architecture, defines tasks
  ├─ Team Lead    → creates GitHub issues, invokes engineers
  └─ Engineers    → write code in parallel, open PRs
    ↓ reports progress
AI Assistant (Claude Code)
  ↓ "Your team is working on 3 issues..."
Human

Echelon is infrastructure for AI systems that need to delegate complex, multi-step engineering work:

• Claude Code Integration — Install Echelon once, then just talk to Claude Code. Claude acts as CEO, delegating to Echelon's management layers.
• MCP Server Ready — Expose Echelon as an MCP tool for any AI assistant. Stream progress events back to conversations.
• API-First Design — Spawn cascades, monitor status, kill subprocesses. Full programmatic control.
• Event Streaming — Real-time progress updates via MessageBus. AI can monitor and report to users continuously.

Example (Claude Code internal):

// User: "Fix all the bugs in the dashboard"
// Claude Code delegates:
await echelon.runCascade({
  directive: "Fix all dashboard bugs",
  monitoring: "continuous",
  reportToUser: true
});
// Claude monitors and updates user: "Your team created 4 issues. 2 PRs are ready for review..."

While designed for AI-to-AI orchestration, Echelon works standalone too:

• Direct CLI — Run echelon in any git repo for autonomous project execution
• Interactive Mode — Terminal UI with org chart, live feed, and approval gates
• Full Control — Approval modes, budget limits, timeout configs—everything is tunable

No agents to configure. No prompt chains to debug. One command.

• Hierarchical planning — A directive cascades through AI management layers (2IC → Eng Lead → Team Lead) before any code is written. Each layer adds specificity.
• Parallel code execution — Engineers run in isolated git worktrees with a sliding-window scheduler. Three engineers by default, configurable.
• GitHub-native — Issues are created, branches are cut, PRs are opened and reviewed. Everything lives in your repo.
• Human-in-the-loop — Approval gates let you review destructive actions (issue creation, code execution) before they happen. Or go full auto.
• Budget controls & cost estimation — Per-layer and total spending limits. Get min/max cost estimates before starting. The system stops when the budget runs out.
• Timeout warnings — Proactive alerts at 50%, 75%, 90% of timeout thresholds. Never wonder if an agent is stuck.
• Terminal UI — Real-time org chart, activity feed, issue tracker, and cost dashboard. Or run headless for CI/automation.
• Session persistence & analytics — Save state, resume later. Deep metrics with echelon analytics for cost breakdown and efficiency tracking.
• Issue consolidation mode — Use --consolidate to create 3-5 larger issues instead of 10+ small ones. Perfect for small teams.
• Zero-config auto-discovery — Just cd into any git repo and run echelon. It detects your project and gets you started.

# Clone the repo
git clone https://github.com/Venin-Client-Systems/echelon.git
cd echelon

# Install dependencies and build
npm install
npm run build

# Link globally (makes `echelon` available anywhere)
npm link

Add tab completion for 10x faster command entry:

# Bash
source completions/echelon-completion.bash
echo "source $(pwd)/completions/echelon-completion.bash" >> ~/.bashrc

# Zsh
mkdir -p ~/.zsh/completions
cp completions/echelon-completion.zsh ~/.zsh/completions/_echelon
# Then add to ~/.zshrc and reload

See docs/SHELL-COMPLETION.md for full instructions.

• Cheat Sheet - All commands on one page
• Testing Docs - Stress test results and quality assurance
• Shell Completion - Tab completion setup

Navigate to any git repo and run:

cd ~/projects/my-app
echelon

First time? Echelon auto-detects your git remote and offers a quick setup:

No config found. Detected: your-org/my-app
Run quick setup? [Y/n]

Approval mode [destructive/all/none] (destructive):

  ✓ Config written to /Users/you/projects/my-app/echelon.config.json

One question, one file, and the TUI launches immediately. That's it.

Already set up? Echelon finds your config automatically and launches the TUI. No flags needed.

Run a directive without the TUI — great for CI, scripts, or quick one-offs:

echelon -d "Add input validation to all API endpoints" --headless

If no config exists, Echelon generates sensible defaults in-memory and runs immediately (no file written). You'll see a note to run echelon init to customize.

See what Echelon would do without any side effects:

echelon -d "Refactor auth into a service layer" --dry-run

For fine-grained control over models, budgets, and safety settings:

echelon init

This walks you through:

• Prerequisite checks (Node, Git, Claude CLI, GitHub CLI)
• Project detection (auto-reads your git remote)
• Model selection per management layer
• Budget and safety configuration

For non-standard config locations or multi-project setups:

echelon --config ~/configs/my-project.json

The only command you need to remember:

echelon              # Interactive mode - handles everything for you

Other useful commands:

echelon --help       # Show all available commands
echelon --version    # Show version number
echelon status       # Check current cascade state (alias: echelon s)
echelon --yolo       # Full autonomous mode (no approvals)

# Advanced usage
echelon -d "Your directive" --headless    # Non-interactive mode
echelon -d "Your directive" --dry-run     # Preview without executing
echelon init                              # Run full setup wizard
echelon sessions list                     # View all sessions
echelon sessions prune                    # Delete completed sessions

Pro tip: Run echelon --help anytime to see the full command reference with examples!

When you run echelon without --config, it searches for echelon.config.json in this order:

1. Current directory — ./echelon.config.json
2. Git root — If you're in a subdirectory, checks the repo root
3. Global config — ~/.echelon/configs/<repo-name>.json

If no config is found:

Layer 0: CEO (Human)     ─── TUI input, approvals, overrides
Layer 1: 2IC (AI)        ─── Strategy, prioritization, workstream planning
Layer 2: Eng Lead (AI)   ─── Architecture, technical design, task breakdown
Layer 3: Team Lead (AI)  ─── Issue creation, sprint management, PR review
Layer 4: Engineers (AI)  ─── Code execution in parallel git worktrees

graph TD
    Start([CEO Directive]) --> Budget{Budget<br/>Available?}
    Budget -->|No| Stop([Abort: Budget Exceeded])
    Budget -->|Yes| 2IC[2IC: Strategic Planning]

    2IC --> Validate2IC{Valid<br/>Output?}
    Validate2IC -->|No| Fail2IC([Cascade Failed])
    Validate2IC -->|Yes| Lead[Eng Lead: Technical Design]

    Lead --> ValidateLead{Valid<br/>Output?}
    ValidateLead -->|No| FailLead([Cascade Failed])
    ValidateLead -->|Yes| InfoReq{Info<br/>Requests?}

    InfoReq -->|Yes| Loopback[Resume Upstream for Answers]
    Loopback --> TeamLead
    InfoReq -->|No| TeamLead[Team Lead: Execution]

    TeamLead --> ValidateTL{Valid<br/>Output?}
    ValidateTL -->|No| FailTL([Cascade Failed])
    ValidateTL -->|Yes| Pending{Pending<br/>Approvals?}

    Pending -->|Yes| WaitApproval[Log Pending Actions]
    Pending -->|No| Complete([Cascade Complete])
    WaitApproval --> Complete

    style Start fill:#e1f5e1
    style Complete fill:#e1f5e1
    style Stop fill:#ffe1e1
    style Fail2IC fill:#ffe1e1
    style FailLead fill:#ffe1e1
    style FailTL fill:#ffe1e1

Each management layer (1-3) is a Claude Code headless session. They reason in natural language and emit structured JSON action blocks.

For detailed architecture diagrams including action lifecycle, scheduler state machine, and error handling flows, see ARCHITECTURE.md.

{
  "action": "create_issues",
  "issues": [
    {
      "title": "[Backend] JWT authentication with refresh tokens",
      "body": "## Overview\n...",
      "labels": ["backend", "ralphy-1"]
    }
  ]
}

Engineers (Layer 4) use Cheenoski — a parallel code execution engine that processes GitHub issues in isolated git worktrees, one branch per task, automatic PR creation.

echelon.config.json:

{
  "project": {
    "repo": "owner/repo",
    "path": "/absolute/path/to/repo",
    "baseBranch": "main"
  },
  "layers": {
    "2ic":       { "model": "opus",   "maxBudgetUsd": 10.0, "maxTurns": 5 },
    "eng-lead":  { "model": "sonnet", "maxBudgetUsd": 5.0 },
    "team-lead": { "model": "sonnet", "maxBudgetUsd": 5.0 }
  },
  "engineers": {
    "engine": "claude",
    "fallbackEngines": ["opencode", "cursor"],
    "maxParallel": 3,
    "createPr": true,
    "prDraft": true,
    "projectBoard": {
      "projectNumber": 1,
      "statusField": "Status",
      "batchField": "Batch"
    }
  },
  "approvalMode": "destructive",
  "billing": "api",
  "maxTotalBudgetUsd": 50.0
}

All fields except project.repo and project.path have defaults. When auto-discovery generates an in-memory config, it uses:

Each layer's maxTurns can be overridden in the config. More turns = more file reading and reasoning, but higher cost.

Control when Echelon asks for your approval before executing actions:

Example configs:

// Destructive mode (recommended) — Approve code changes, auto-approve queries
{
  "approvalMode": "destructive",
  "project": { "repo": "owner/repo", "path": "/path" }
}

// All mode — Approve everything (useful for testing)
{
  "approvalMode": "all",
  "project": { "repo": "owner/repo", "path": "/path" }
}

// None mode — Full autonomous (pair with budget limits!)
{
  "approvalMode": "none",
  "maxTotalBudgetUsd": 10.0,  // Safety net!
  "project": { "repo": "owner/repo", "path": "/path" }
}

Override at runtime:

echelon -d "Add tests" --approval-mode none --headless  # Full auto
echelon --yolo  # Alias for --approval-mode none (also skips permission prompts)

Echelon engineers (Cheenoski) support multiple AI backends for code execution:

Fallback engines — Automatically retry failed tasks with different engines:

{
  "engineers": {
    "engine": "claude",
    "fallbackEngines": ["opencode", "cursor"],  // Try these if claude fails
    "maxParallel": 3
  }
}

When an engineer fails (timeout, crash, no code changes), Cheenoski automatically retries with the next engine in the fallback list. Useful for:

• Rate limits — Switch to alternative backend when primary is throttled
• Task-specific performance — Some engines excel at certain domains
• Cost optimization — Try cheaper engines first, fallback to premium

Engine selection happens per-task, so different engineers can use different backends simultaneously.

Choose how Anthropic API usage is calculated:

{
  "billing": "api"  // or "max"
}

• api (default) — Standard API pricing, pay-per-token. Recommended for most users.
• max — Claude Pro/Max plan. Lower concurrent request limits, but no per-token charges. Use if you have an active Max subscription.

When to use max mode:

• You have Claude Pro or Max plan
• Working on large projects (budget limits don't apply)
• Concerned about runaway API costs

Trade-offs:

• max mode has stricter rate limits (fewer concurrent agents)
• api mode has higher throughput but accumulates charges

Usage: echelon [options] [command]

Options:
  -c, --config <path>          Path to echelon.config.json (auto-discovered if omitted)
  -d, --directive <text>       CEO directive to execute
  --headless                   Run without TUI (headless mode)
  --dry-run                    Show planned cascade without executing
  --resume                     Resume the most recent session
  -v, --verbose                Enable debug logging
  --approval-mode <mode>       Override approval mode (destructive, all, none)
  --yolo                       Full autonomous mode — no approvals, no permission prompts
  --consolidate                Create 3-5 larger issues instead of 10+ small ones (for small teams)
  --telegram                   Start in Telegram bot mode
  -V, --version                Output version number
  -h, --help                   Display help

Commands:
  run [options]                Run the orchestrator (default)
  init                         Interactive config generator (full wizard)
  status                       Show current cascade status
  analytics [session-id]       Show detailed session analytics and metrics
  sessions list                List all saved sessions
  sessions prune               Delete completed/failed sessions
  sessions delete <id>         Delete a specific session

# First time — auto-detects repo, quick setup, launches TUI
echelon

# Give a directive interactively via TUI
echelon

# Headless one-liner
echelon -d "Fix all TODO comments in src/" --headless

# Dry run to preview the cascade
echelon -d "Add rate limiting to API" --dry-run

# Full auto — no approval prompts
echelon -d "Add unit tests" --headless --approval-mode none

# Resume where you left off
echelon --resume

# Explicit config
echelon --config path/to/echelon.config.json

# Session management
echelon status                           # Show current cascade status
echelon analytics                        # Show detailed metrics for latest session
echelon analytics <session-id>           # Analyze specific session
echelon sessions list                    # List all saved sessions
echelon sessions prune                   # Delete completed/failed sessions
echelon sessions delete <session-id>     # Delete a specific session

# Issue consolidation for small teams
echelon --consolidate -d "Add auth"      # Create 3-5 larger issues instead of 10+

# Telegram bot mode
echelon --telegram                       # Start as Telegram bot

# YOLO mode — full autonomous, no approvals
echelon -d "Fix bugs" --yolo --headless

Once inside the TUI, type these at the CEO prompt:

┌─ Echelon ──────────────────────── project ────┐
│ ┌─ Org ──────────┐  ┌─ Feed ────────────────┐ │
│ │ CEO     ● you  │  │ [2IC] Breaking down.. │ │
│ │ 2IC     ◆ plan │  │ [Lead] JWT + refresh  │ │
│ │ Lead    ○ idle │  │ [TL] Created #42...   │ │
│ │ TL      ○ idle │  │ [Eng#1] Working #42   │ │
│ │ Eng #1  ▶ code │  │ [Eng#2] PR #12 open   │ │
│ └────────────────┘  └───────────────────────┘ │
│ ┌─ Issues ───────┐  Cost: $2.40 | Time: 8m   │
│ │ #42 JWT    ▶  │                             │
│ │ #43 RBAC   ○  │                             │
│ └────────────────┘                             │
│ CEO > _                                        │
└────────────────────────────────────────────────┘

Run Echelon as a Telegram bot for mobile-first operation:

echelon --telegram

1. Create a bot via @BotFather:

   • Send /newbot and follow prompts
   • Save the bot token

2. Get your chat ID:

   • Message your bot
   • Visit https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
   • Find "chat":{"id":123456789} in the response

3. Configure via echelon init (Step 5) or add to echelon.config.json:

{
  "telegram": {
    "token": "123456:ABC...",
    "chatId": "123456789",
    "allowedUserIds": [123456789],
    "health": {
      "enabled": true,
      "port": 3000,
      "bindAddress": "0.0.0.0"
    }
  }
}

Override config with environment variables (useful for production):

export ECHELON_TELEGRAM_BOT_TOKEN="123456:ABC..."
export ECHELON_TELEGRAM_CHAT_ID="123456789"
export ECHELON_TELEGRAM_ALLOWED_USERS="123456789,987654321"  # Comma-separated

# Health monitoring
export ECHELON_HEALTH_ENABLED="true"
export ECHELON_HEALTH_PORT="3000"
export ECHELON_HEALTH_BIND="0.0.0.0"

Telegram bot mode includes an HTTP health check server (default port 3000):

curl http://localhost:3000/health
# {"status":"ok","uptime":120,"lastActivity":"2025-01-15T10:30:00Z"}

Useful for monitoring bot availability in production (Docker, systemd, etc.).

• Mobile approval gates — Approve/reject actions from your phone
• Real-time progress — Live updates from all layers and engineers
• Health monitoring — HTTP endpoint for uptime checks
• User auth — Only responds to configured user IDs
• Async question handling — CEO can ask you questions mid-cascade (5-minute timeout)

You: Add JWT authentication to the API

[CEO]: Starting cascade...
[2IC]: Breaking directive into workstreams:
       1. JWT token generation
       2. Refresh token flow
       3. Middleware integration
[Eng Lead]: Designed auth architecture
[Team Lead]: Created issues #42, #43, #44

⚠️ Approval needed: Create 3 GitHub issues?
[Approve] [Reject]

You: Approve

[Team Lead]: Issues created, starting Cheenoski...
[Eng#1]: Working on #42 (JWT generation)
[Eng#2]: Working on #43 (refresh flow)
[Eng#1]: PR #45 created for #42
...

Sessions are saved to ~/.echelon/sessions/<project-timestamp>/:

• state.json — Full state (agent sessions, messages, issues, costs)
• transcript.md — Human-readable activity log

Resume your last session:

echelon --resume

Agent context carries over — Claude sessions are resumed with claude -r <session-id>, so the AI remembers what it was doing.

"ANTHROPIC_API_KEY not set"

export ANTHROPIC_API_KEY="sk-ant-..."  # Add to ~/.bashrc or ~/.zshrc

"GITHUB_TOKEN not set or invalid"

gh auth login  # Interactive auth
# OR
export GITHUB_TOKEN="ghp_..."  # Personal access token

"Claude Code session not found"

• Agent sessions expire after inactivity
• Start fresh: echelon (don't use --resume)
• Check ~/.echelon/sessions/ for orphaned state

"Budget exceeded for layer: 2ic"

• Each layer has a budget (layers.2ic.maxBudgetUsd)
• Increase in config or reduce task complexity
• Use haiku for simpler tasks (cheaper)

"Action validation failed: Invalid action type"

• Agent returned malformed JSON action block
• Check logs: ~/.echelon/logs/echelon-*.log
• Usually means agent hit context limits (reduce task scope)

Telegram bot not responding

• Verify env vars: ECHELON_TELEGRAM_BOT_TOKEN, ECHELON_TELEGRAM_CHAT_ID
• Check bot token via @BotFather
• Verify chat ID: curl https://api.telegram.org/bot<TOKEN>/getUpdates
• Check allowedUserIds matches your Telegram user ID

"gh: command not found"

# macOS
brew install gh

# Linux
sudo apt install gh  # Debian/Ubuntu
sudo dnf install gh  # Fedora

Engineers (Cheenoski) stuck on "Processing issue #42"

• Check agent logs in worktree: ~/.echelon/worktrees/<branch>/
• Hard timeout: 10 minutes (configurable: engineers.hardTimeoutMs)
• Kill stuck process: pkill -f "claude.*issue-42"

Slow cascade (>5 minutes for simple tasks)

• Use haiku for lower layers (Eng Lead, Team Lead) — faster but less capable
• Reduce maxTurns for non-critical layers
• Use --dry-run to preview cascade before executing

High API costs (>$5 for small features)

• Switch expensive layers to sonnet instead of opus
• Set tighter per-layer budgets (layers.2ic.maxBudgetUsd: 2.0)
• Use billing: "max" if you have Claude Pro (no per-token charges, but lower limits)

Engineers making no progress

• Check issue descriptions — vague specs = poor results
• Ensure domain labels match ([Backend], [Frontend], etc.)
• Try different engine: engineers.engine: "opencode" or "cursor"

Worktree conflicts

# Clean up orphaned worktrees
git worktree list
git worktree remove <path>  # For each orphaned worktree

Enable verbose logging:

echelon -d "..." --verbose

Logs go to ~/.echelon/logs/echelon-<timestamp>.log. Includes:

• Agent API calls and responses
• Action parsing (JSON extraction)
• Budget tracking
• Error stack traces

• Issues: https://github.com/Venin-Client-Systems/echelon/issues
• Docs: ARCHITECTURE.md, SECURITY.md, LOGGING.md
• Examples: Check examples/ directory for sample configs

src/
  index.ts                    # Entry point — auto-discovery, routes to TUI or headless
  cli.ts                      # Commander arg parsing
  commands/init.ts            # Setup wizard + quick init

  core/
    orchestrator.ts           # Main hierarchical cascade loop
    agent.ts                  # Claude Code session spawn/resume
    message-bus.ts            # EventEmitter routing between layers
    action-parser.ts          # Extract JSON action blocks from agent text
    action-executor.ts        # Execute or queue actions for approval
    state.ts                  # Persistent state load/save/resume
    session.ts                # Session management (list, prune, delete)

  actions/
    github-issues.ts          # gh issue create/update/close
    cheenoski.ts              # Invoke Cheenoski runner
    git.ts                    # Branch management
    review.ts                 # PR review

  ui/                         # Ink (React for CLI) components
    App.tsx                   # Root layout
    OrgChart.tsx              # Agent status sidebar
    Feed.tsx                  # Scrollable activity log
    IssuePanel.tsx            # GitHub issues tracker
    Input.tsx                 # CEO command input
    StatusBar.tsx             # Cost, time, project info
    ApprovalPrompt.tsx        # Inline approval UI
    hooks/useEchelon.ts       # Bridge orchestrator state to React

  lib/
    types.ts                  # Zod schemas for config, actions, state
    paths.ts                  # Atomic JSON writes
    logger.ts                 # Structured logging
    config.ts                 # Config loader, auto-discovery, default generation
    git-detect.ts             # Git remote/root/branch detection
    transcript.ts             # Markdown transcript writer
    prompts.ts                # System prompts for each layer

cheenoski/                    # Bundled parallel execution engine

• ARCHITECTURE.md — Detailed system architecture, flow diagrams, and internals
• SECURITY.md — Security model, credential handling, and best practices
• LOGGING.md — Structured logging, debug mode, and log analysis

Generate API documentation locally:

npm run docs:api

The documentation covers:

• Configuration — EchelonConfig, LayerConfig, project settings
• Core — Orchestrator, MessageBus, agent lifecycle
• Actions — All action types and schemas
• Types — Complete type definitions and schemas

Issues and PRs are welcome. This is early-stage software — expect rough edges.

For AI integration developers:

• See ARCHITECTURE.md for MessageBus event streaming
• Check src/core/orchestrator.ts for programmatic API usage
• Review src/lib/types.ts for all event and action schemas

# Development
npm run dev -- -d "your directive" --headless

# Type checking
npm run typecheck

# Generate API docs
npm run docs:api

MIT © 2026 Venin Client Systems

Silent infrastructure that "just works"
Built by VENIN (George Atkinson & Claude Opus 4.6)
Designed for AI-to-AI orchestration