agent-delegator 0.4.0

Agent-agnostic AI CLI delegation with federated model failover

agent-delegator

Agent-agnostic AI CLI delegation with federated model failover, intelligent routing, and a real-time Mission Control dashboard.

---

Why agent-delegator?

You have multiple AI agents installed — Claude, OpenCode, Copilot, Codex, Gemini — but switching between them is manual, error-prone, and wastes time. agent-delegator solves this by:

• Failing over automatically when an agent is down, rate-limited, or returns errors
• Routing intelligently based on workflow type (code review → Claude, implementation → OpenCode)
• Learning from history to prioritize the best agent for each task type
• Monitoring everything in a beautiful local dashboard with real-time metrics

No more copy-pasting prompts between chat windows. No more discovering your preferred agent is down after you sent a task. Just describe what you want and let agent-delegator pick the best available agent.

---

Features

Core Engine

Feature	Description
Federated Failover	Automatically falls back to the next best agent when the primary fails
Intelligent Routing	Route implementation tasks to OpenCode, code_review to Claude based on a configurable matrix
Health Checks	Continuously monitors agent availability and marks unhealthy agents for cooldown
Circuit Breaker	Temporarily disables failing agents to prevent cascading failures
Auto-Learning	Analyzes past delegations to optimize agent rankings and priority order
Metrics & Cost Tracking	Tracks success rates, duration, fallback counts, and estimated costs per agent
Project Scoping	Per-project .agent-delegator.json configs with isolated state and routing rules

Mission Control Dashboard

A local-only web UI (no cloud, no sign-up) that runs on http://127.0.0.1:8765:

Feature	Description
Live Task Monitor	Watch active tasks in real-time with auto-refreshing output
Agent Health Cards	Visual status of all agents with success-rate progress bars
Delegation History	Filterable table with replay, retry, and "like" functionality
Analytics	7/14/30-day success rates, cost breakdowns, failure type charts, agent rankings
A/B Model Comparison	Run the same task on two models side-by-side and compare results
Task Queue	Queue tasks for later or schedule them with cron expressions
Route Editor	Drag-and-drop provider priority, add/remove workflow routes
Notifications	Telegram and Slack webhooks for task completion, failures, and cooldown alerts
Project Switcher	Switch between projects without leaving the dashboard
Keyboard Shortcuts	Vim-like shortcuts (L live, O logs, H history, Cmd+K exec)

Security

Built with a security-first mindset for a tool that processes code and executes commands:

• API Key Authentication on all dashboard endpoints
• CSRF Protection via Origin/Referer validation + X-Requested-With
• Rate Limiting using direct IP (no X-Forwarded-For trust)
• XSS Prevention — all dynamic DOM content escaped, no inline onclick with user data
• SSRF Protection — blocks localhost, private IPs, and metadata endpoints for webhooks
• Input Validation — shell metacharacters blocked, length limits enforced
• Encrypted Secrets — Fernet encryption for Telegram tokens and Slack URLs at rest
• Security Headers — CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy

---

Supported Agents

Agent	CLI Command	Status
Claude	claude	✅ Supported
OpenCode	opencode	✅ Supported
GitHub Copilot	copilot	✅ Supported
Codex	codex	✅ Supported
Gemini (Antigravity)	antigravity	✅ Supported

Adding a new agent requires only a few lines in .agent-delegator.json. See INTEGRATION.md for details.

---

Install

Quick Install (recommended)

pip install agent-delegator

This includes the full package with the Mission Control dashboard. The dashboard requires zero extra dependencies — it's pure Python stdlib + static HTML.

Development Install

git clone https://github.com/amardeep434/agent-delegator.git
cd agent-delegator
pip install -e ".[dev]"

Optional Dependencies

# With encryption support for dashboard secrets (recommended)
pip install "agent-delegator[secure]"

# Development + testing + building
pip install "agent-delegator[dev]"

Skip the Dashboard

If you only want the CLI and never use the dashboard, disable it at runtime:

# One-time
AGENT_DELEGATOR_NO_DASHBOARD=1 agent-delegator dashboard

# Session-wide
export AGENT_DELEGATOR_NO_DASHBOARD=1

# Or disable per-project
agent-delegator init
# Edit .agent-delegator.json: "disable_dashboard": true

---

Quick Start

1. Initialize your project

cd my-project
agent-delegator init

This creates .agent-delegator.json with sensible defaults.

2. Execute a task with automatic failover

agent-delegator exec --model federated-coding --task "Add unit tests for OrderRepository"

federated-coding is a logical model that tries the best available coding agent, falling back automatically.

3. Check system status

agent-delegator status
agent-delegator health

4. Launch the dashboard

agent-delegator dashboard
# Open http://127.0.0.1:8765

5. Learn from past delegations

agent-delegator learn

This re-ranks your agents based on success rates and response times.

---

CLI Reference

# Execute with options
agent-delegator exec --model claude-sonnet-4-6 --task "Refactor this function" --stream

# Route a specific workflow
agent-delegator exec --model federated-coding --workflow code_review --task "Review PR #42"

# View metrics
agent-delegator metrics --days 7 --agent opencode

# Optimize rankings manually
agent-delegator optimize

# Clean up stale worktrees
agent-delegator cleanup --ttl 24

# Check capabilities of an agent
agent-delegator capabilities --agent claude

Global Flags

Flag	Description
--no-dashboard	Disable dashboard features for this session

---

Configuration

Project Config (.agent-delegator.json)

{
  "preferred_models": {
    "implementation": "federated-coding",
    "code_review": "claude:claude-sonnet-4-6",
    "research": "federated-sonnet"
  },
  "provider_priority": ["opencode", "claude", "copilot"],
  "worktree_ttl_hours": 24,
  "cooldown": {
    "failure_threshold": 3,
    "base_minutes": 5,
    "max_minutes": 60
  },
  "disable_dashboard": false
}

Routing Matrix

Define which agent handles which workflow/task combination:

{
  "routing_matrix": {
    "_any_agent_": {
      "subagent-driven": {
        "implementation": {
          "delegate_to": "opencode",
          "preferred_model": "federated-coding"
        },
        "code_review": {
          "delegate_to": "claude",
          "preferred_model": "claude-sonnet-4-6"
        }
      }
    }
  }
}

---

How It Works

User Request
    │
    ▼
┌─────────────────┐
│  Route Resolver │──→ Match workflow/task against routing matrix
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Health Check   │──→ Is the preferred agent available?
└─────────────────┘
    │ Yes          │ No
    ▼              ▼
┌────────┐    ┌─────────────────┐
│ Execute│    │  Failover Loop  │──→ Try next agent in priority order
└────────┘    └─────────────────┘
    │
    ▼
┌─────────────────┐
│  Record Metrics │──→ Success rate, duration, cost, fallback count
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Notify (opt)   │──→ Telegram/Slack webhook
└─────────────────┘

---

Dashboard Screenshots

The dashboard provides a single-pane-of-glass view into all your AI agent activity:

• Live View — Real-time output from active tasks with auto-polling
• Logs — Searchable, filterable delegation history with error highlighting
• Analytics — Bar charts for success rates, cost breakdowns, failure classifications
• Compare — Side-by-side A/B testing of two models on the same prompt
• Queue — Manage pending and scheduled tasks
• Settings — Drag-and-drop provider priority, circuit breaker config, notification setup

All data stays local. The dashboard binds to 127.0.0.1 only and uses a machine-bound API key for authentication.

---

Development

Running Tests

# All tests
python -m pytest tests/ -v

# Dashboard tests only
python -m pytest tests/test_dashboard.py tests/test_dashboard_security.py -v

# Security regression tests
python -m pytest tests/test_dashboard_security.py -v

Building

python -m build

Project Structure

agent-delegator/
├── cli.py              # CLI entry point
├── executor.py         # Task execution & failover logic
├── router.py           # Workflow → agent routing
├── resolver.py         # Logical model → provider resolution
├── registry.py         # Agent configuration & routing matrix
├── health.py           # Agent health checks
├── cooldowns.py        # Circuit breaker & cooldown management
├── metrics.py          # Delegation metrics & success tracking
├── optimizer.py        # Auto-learning & ranking optimization
├── dashboard/
│   ├── server.py       # HTTP server with auth & security headers
│   ├── api.py          # REST API endpoints
│   └── templates/
│       └── dashboard.html  # Mission Control UI
└── secrets.py          # Fernet encryption for sensitive config

---

Release Automation

This project uses GitHub Actions for continuous delivery:

1. CI Workflow — Runs tests on Python 3.10–3.13 for every PR and push
2. Release Workflow — Auto-bumps version based on Conventional Commits:
   • feat: → minor version bump
   • fix: → patch version bump
   • BREAKING CHANGE: → major version bump
3. PyPI Publishing — Builds and publishes automatically on version bump

Setup (one-time)

1. Go to PyPI Account Settings → API Tokens
2. Create a token scoped to the agent-delegator project
3. In your GitHub repo: Settings → Secrets and variables → Actions → New repository secret
4. Name: PYPI_API_TOKEN, Value: your token

Trigger a Release

Merge a PR with a Conventional Commit message:

git commit -m "feat: add Gemini agent support"
git push origin main
# → Workflow detects feat: → bumps minor → publishes v0.2.0

---

Contributing

We use Conventional Commits to enable automatic versioning and PyPI publishing.

Local Setup

# Ensure commit-msg hook is active
git config core.hooksPath .githooks

Commit Examples

git commit -m "feat: add dashboard analytics tab"      # triggers minor release
git commit -m "fix(api): handle empty task input"      # triggers patch release
git commit -m "docs: update install instructions"      # no release
git commit -m "test: add security regression tests"    # no release

Pull Requests

All PRs are checked by the commitlint workflow. Commits must follow the format:

<type>[(scope)][!]: <description>

Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

---

Security

See AGENTS.md for the full security checklist and development guidelines.

If you discover a security vulnerability, please email [e-mail] rather than opening a public issue.

---

License

MIT © Amardeep

---

Acknowledgments

Built with inspiration from:

• Aider — AI pair programming
• Fabric — AI pattern framework
• OpenRouter — Unified LLM API