agent-orchestrator

Three AI agents. One brain. Zero downtime.

A terminal-based multi-agent orchestrator that wraps Claude, Codex, and Gemini CLIs with automatic failover. When one agent hits its limit, the next one picks up seamlessly. All agents share context through a knowledge base server. $60/month for three premium AI agents — no API billing.

How It Works

You type a message
       |
       v
  [Orchestrator]
       |
       +---> Try Agent 1 (Claude) ---> Success? Return response
       |            |
       |         Failed/Down
       |            |
       +---> Try Agent 2 (Codex) ---> Success? Return response
       |            |
       |         Failed/Down
       |            |
       +---> Try Agent 3 (Gemini) --> Success? Return response
       |
  All failed? Show error + recovery options

Each message is routed through a role chain — an ordered list of agents to try. Roles include:

• orchestrator — planning, architecture, high-level reasoning (default: Claude > Codex > Gemini)
• implementation — code execution, build tasks (default: Codex > Claude > Gemini)
• uidocs — frontend, design, documentation (default: Gemini > Codex > Claude)
• review — code review, validation (default: Claude > Codex > Gemini)

Every role, chain order, and model is configurable.

Features

• Next-man-up failover — if an agent is down, the next one in the chain takes over automatically
• Auto-downtime detection — detects rate limits, quota exhaustion, auth failures, and auto-disables agents with cooldown timers
• CLI wrapping — uses your existing Claude/Codex/Gemini CLI subscriptions, not per-token API billing
• API mode available — switch any agent to API mode if you prefer
• Configurable name — call it whatever you want, not hardcoded
• Knowledge base integration — searches your KB server for relevant context before every response
• Colored output — each agent has its own color for easy identification
• Role-based routing — impl: prefix routes to implementation chain, ui: to UI chain
• Task management — switch between project contexts with /task
• Service management — manually disable/enable agents, set timed downtimes
• Smoke testing — test all agents with one command
• Directory whitelisting — control which directories agents can access

Quickstart

git clone https://github.com/willynikes2/agent-orchestrator.git
cd agent-orchestrator
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 daniel.py --setup

The setup wizard asks:

1. What to name your orchestrator (default: "agent")
2. Which mode for each agent (CLI or API)
3. API keys (optional in CLI mode)
4. Model IDs
5. Role chain preferences

Then just run:

python3 daniel.py

Or install globally:

ln -s $(pwd)/daniel.py ~/.local/bin/agent-orchestrator

Prerequisites

• Python 3.10+
• At least one AI CLI installed:
  • claude — Claude Code CLI
  • codex — OpenAI Codex CLI
  • gemini — Google Gemini CLI

Commands

/help                 Show all commands
/setup                Rerun setup wizard
/models               Show current model configuration
/chains               Show role fallback chains
/task                 Show current task
/task list            List known tasks
/task <id>            Switch task context
/run                  Run orchestrator script for current task
/smoke                Smoke test all enabled agents
/kb <query>           Search the knowledge base
/service status       Show agent status (up/down/unavailable)
/service down <agent> <minutes|manual>   Disable an agent
/service up <agent>   Re-enable an agent
/service recover      Re-enable ALL disabled agents
/allow-dir list       List approved directories
/allow-dir add <path> Approve a directory
/allow-dir rm <path>  Remove an approved directory
/quit                 Exit

impl: <message>       Route to implementation chain
ui: <message>         Route to UI/docs chain

Cost Model

Service	Monthly Cost	What You Get
Claude Pro	~$20	Claude Code CLI with Opus
OpenAI subscription	~$20	Codex CLI
Google subscription	~$20	Gemini CLI
Total	~$60	Three premium AI agents

No per-token API billing. CLI wrapping uses your subscription tiers. When one agent hits its usage cap, the orchestrator automatically routes to the next available agent.

Knowledge Base Integration

If you're running knowledge-base-server, the orchestrator automatically searches it for relevant context before each response.

# Search KB manually
/kb docker networking

# KB context is auto-injected when you have an active task
/task my-project
> How should I set up the reverse proxy?
# Agent receives KB results for "my-project" as context

Set kb_port in config if your KB server runs on a non-default port.

Configuration

Config lives at ~/.config/agent-orchestrator/config.json:

{
  "name": "agent",
  "tasks_root": "~/tasks",
  "kb_port": "3838",
  "claude_mode": "cli",
  "codex_mode": "cli",
  "gemini_mode": "cli",
  "models": {
    "claude": "claude-sonnet-4-5",
    "codex": "gpt-5",
    "gemini": "gemini-2.5-pro"
  },
  "chains": {
    "orchestrator": ["claude", "codex", "gemini"],
    "implementation": ["codex", "claude", "gemini"],
    "uidocs": ["gemini", "codex", "claude"],
    "review": ["claude", "codex", "gemini"]
  }
}

Everything is configurable. Change the name, reorder chains, swap models, switch between CLI and API mode per agent.

Auto-Downtime Detection

The orchestrator automatically detects when agents are unavailable:

Error Pattern	Action	Recovery
Claude usage cap exhausted	Disable until reset time	Auto-recovers at reset
Rate limit (any agent)	5-minute cooldown	Auto-recovers
Auth failure	Manual disable	/service up <agent>
Model not found	Manual disable	Fix model, /service up
CLI not found	Marked unavailable	Install CLI

Use /service recover to re-enable all disabled agents at once.

Architecture

daniel.py (single file, ~1100 lines)
  |
  +-- Config: ~/.config/agent-orchestrator/config.json
  |
  +-- Agent Calls:
  |     +-- _call_claude_cli()  / _call_claude_api()
  |     +-- _call_codex_cli()   / _call_codex_api()
  |     +-- _call_gemini_cli()  / _call_gemini_api()
  |
  +-- Failover: _role_chain() -> _chat_once() -> try each agent
  |
  +-- Auto-downtime: _apply_auto_downtime() detects errors
  |
  +-- Context: _shared_context() + _kb_search()
  |
  +-- Output: colored, per-agent formatting

Single-file design is intentional. Easy to understand, easy to modify, easy to deploy.

Extending

Want to add a new agent? Three steps:

1. Add it to the AGENTS tuple
2. Write _call_newagent_cli() and _call_newagent_api() functions
3. Add it to _call_agent() dispatcher and default chains

See the existing agent functions for the pattern. Each is ~30 lines.

License

MIT

Author

Built by Shawn Daniel — powered by the agents it orchestrates.