AGW — Agent Gateway

Multi-agent task router and executor for Claude Code, Codex CLI, and Gemini CLI.

Submit a task → AGW picks the best agent → agent executes → you get results + logs + cost data.

Quick Start

# Install globally
npm i -g @sooneocean/agw

# Start the daemon
agw daemon start

# Run a task
agw run "refactor auth.ts"

# Run with specific agent, priority, timeout, tags
agw run "quick rename" --agent codex --priority 5 --timeout 30000 --tag "refactor,urgent"

# Search tasks
agw search "auth" --status completed --agent claude

# Multi-agent combo (pipeline)
agw combo preset analyze-implement-review "fix the login bug"

# Check costs
agw costs

# Live dashboard
agw dashboard

# Run task after another completes
agw run "build project" --after <testTaskId>

# Open Web UI
open http://127.0.0.1:4927/ui

Features

Feature	Description
Smart Routing	LLM classifier (Haiku) + keyword fallback + agent learning
3 Agents	Claude (complex reasoning), Codex (terminal ops), Gemini (research)
Combos	Multi-agent collaboration: pipeline, map-reduce, review-loop, debate
Task Tags	Label and filter tasks with custom tags
Task Timeout	Per-task timeout with auto-cancel
Task Cancel/Retry	Cancel running tasks, retry failed ones
Task Search	Multi-field search: prompt, status, agent, tag, date range
Priority Queue	1-5 priority with per-agent concurrency limits
Cost Tracking	Per-task cost recording, daily/monthly quotas, auto-purge
Workflows	Sequential or parallel multi-step task chains
DAG Execution	Dependency graph with parallel execution of independent nodes
DSL	claude: "analyze" | codex: "implement" syntax
Scheduler	Recurring jobs (persisted to SQLite)
Webhooks	HTTP POST notifications on task events (persisted)
Agent Learning	Tracks per-agent performance, feeds back into routing
Templates	Reusable parameterized task definitions
Snapshots	Full database backup and restore
Batch	Submit up to 50 tasks with concurrency control
Auth	Bearer token or loopback-only
Workspace Sandbox	allowedWorkspaces whitelist + realpath validation
Web UI	Real-time dashboard at /ui
SSE Streaming	Live stdout/stderr via /tasks/:id/stream
Structured Logging	Pino JSON logs with configurable level
Rate Limiting	Token bucket per IP, configurable
Multi-Tenant	API key isolation with per-tenant quotas
Task Dependencies	Run tasks after dependencies complete
Task Notes	Annotate tasks with contextual notes
Task Pinning	Pin important tasks to prevent auto-purge
OpenAPI Docs	Auto-generated Swagger UI at /docs

MCP Server

AGW is an MCP (Model Context Protocol) server. Connect from any MCP-compatible IDE.

Setup (Claude Code)

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agw": { "command": "agw", "args": ["mcp"] }
  }
}

MCP Tools

Tool	Description
agw_run	Submit task to best AI agent (prompt, agent, priority, tags, timeout)
agw_combo	Multi-agent collaboration (preset or custom pattern)
agw_status	Check task status and results
agw_search	Search tasks by prompt, status, agent, tag
agw_agents	List available agents with health status

MCP Resources

URI	Content
agw://agents	Agent list with health status and capabilities
agw://stats	System statistics, agent ranking, costs

Configuration

Config file: ~/.agw/config.json

{
  "port": 4927,
  "authToken": "your-secret-token",
  "allowedWorkspaces": ["/home/user/projects"],
  "maxConcurrencyPerAgent": 3,
  "dailyCostLimit": 5.00,
  "monthlyCostLimit": 50.00,
  "maxPromptLength": 100000,
  "maxWorkflowSteps": 20,
  "agents": {
    "claude": { "enabled": true, "command": "claude", "args": [] },
    "codex": { "enabled": true, "command": "codex", "args": [] },
    "gemini": { "enabled": false, "command": "gemini", "args": [] }
  }
}

Environment variables (override config file):

Variable	Description
AGW_PORT	Server port (default: 4927)
AGW_AUTH_TOKEN	Bearer token for API auth
ANTHROPIC_API_KEY	API key for LLM routing
AGW_LOG_LEVEL	Log level: debug, info, warn, error (default: info)
AGW_LOG_PRETTY	Set to 1 for human-readable logs in dev

API

Tasks

Method	Path	Description
POST	/tasks	Create and execute a task
GET	/tasks/:id	Get task details
GET	/tasks/:id/stream	SSE stream (stdout/stderr/done)
GET	/tasks	List tasks (?limit=&offset=&tag=)
GET	/tasks/search	Search tasks (?q=&status=&agent=&tag=&since=&until=)
POST	/tasks/:id/cancel	Cancel a running/pending task
POST	/tasks/:id/retry	Retry a failed/cancelled task
POST	/tasks/:id/replay	Replay a completed task
PATCH	/tasks/:id	Update task tags/priority
DELETE	/tasks/:id	Delete a completed/failed task
POST	/tasks/:id/notes	Add note to task
GET	/tasks/:id/notes	List task notes
DELETE	/notes/:noteId	Delete a note
POST	/tasks/:id/pin	Pin task
POST	/tasks/:id/unpin	Unpin task
GET	/tasks/queue	View execution queue
GET	/tasks/export	Export tasks (JSON/CSV)
GET	/tasks/histogram	Duration histogram

Combos

Method	Path	Description
POST	/combos	Create and start a combo
POST	/combos/preset/:presetId	Run a built-in preset
GET	/combos/presets	List available presets
GET	/combos/:id	Get combo status and results
GET	/combos	List combos
POST	/combos/:id/replay	Replay a combo

Workflows

Method	Path	Description
POST	/workflows	Create workflow
GET	/workflows/:id	Get workflow status
GET	/workflows	List workflows

Agents

Method	Path	Description
GET	/agents	List agents
POST	/agents/:id/health	Trigger health check
GET	/agents/:id/stats	Agent performance stats
POST	/agents/:id/enable	Enable agent
POST	/agents/:id/disable	Disable agent
GET	/agents/detect	Detect installed agents
GET	/agents/ranking	Agent ranking by performance

Templates

Method	Path	Description
GET	/templates	List templates
POST	/templates	Register custom template
POST	/templates/execute	Instantiate and execute
GET	/templates/:id	Get template by ID
DELETE	/templates/:id	Delete template

Scheduler

Method	Path	Description
GET	/scheduler/jobs	List scheduled jobs
POST	/scheduler/jobs	Create job
DELETE	/scheduler/jobs/:id	Remove job
GET	/scheduler/jobs/:id	Get job by ID
POST	/scheduler/jobs/:id/enable	Enable job
POST	/scheduler/jobs/:id/disable	Disable job

Other

Method	Path	Description
GET	/costs	Cost summary
POST	/batch	Submit batch tasks (max 50)
GET	/webhooks	List webhooks
POST	/webhooks	Register webhook
DELETE	/webhooks	Remove webhook
GET	/memory	List memory entries
PUT	/memory/:key	Set memory entry
GET	/export	Export configuration
POST	/import	Import configuration
POST	/snapshots	Create DB snapshot
GET	/snapshots	List snapshots
POST	/snapshots/:id/restore	Restore snapshot
DELETE	/snapshots/:id	Delete snapshot
GET	/memory/:key	Get memory entry
DELETE	/memory/:key	Delete memory entry
GET	/capabilities	Agent capabilities
GET	/capabilities/:agentId	Get agent capabilities
POST	/capabilities/match	Find best agent for task
GET	/health	Health check
GET	/health/ready	Readiness probe
GET	/metrics	Detailed metrics
GET	/metrics/prometheus	Prometheus format metrics
GET	/events	SSE event stream
GET	/tasks/stats	Task statistics
GET	/audit	Audit log entries
GET	/audit/count	Audit entry count
GET	/costs/breakdown	Cost breakdown by agent/day
POST	/webhooks/test	Send test webhook event
POST	/combos/:id/cancel	Cancel a running combo
GET	/agents/:id/config	Agent configuration
GET	/mcp	MCP server info
GET	/docs	Swagger UI (OpenAPI)
GET	/ui	Web dashboard

CLI Commands

agw run <prompt>         Submit a task (--agent, --priority, --timeout, --tag, --background, --cwd, --raw, --after <taskId>)
agw status <taskId>      Check task status
agw history              List recent tasks (--limit N)
agw search [query]       Search tasks (--status, --agent, --tag, --since)
agw cancel <taskId>      Cancel a running/pending task
agw retry <taskId>       Retry a failed/cancelled task
agw agents               List agents / agw agents check
agw combo presets        List combo presets
agw combo preset <id>    Run a preset combo
agw combo run <json>     Run custom combo
agw combo status <id>    Check combo status
agw combo list           List recent combos
agw workflow run|status|list
agw costs                Show cost summary
agw dashboard            Live terminal dashboard (--once)
agw stats                Show task statistics and trends
agw events               Stream live system events
agw config show|get|set|path  Manage daemon configuration
agw watch <taskId>       Watch a task in real-time
agw combo dsl <expr> <input>  Run combo from DSL syntax
agw agents detect        Detect installed CLI tools
agw agents check         Trigger health checks
agw delete <taskId>      Delete a completed/failed task
agw pin <taskId>         Pin task to prevent auto-purge
agw unpin <taskId>       Unpin task
agw note <taskId> <msg>  Add a note to a task
agw notes <taskId>       List task notes
agw template list        List available templates
agw template execute <id> Execute a template (--param key=value)
agw combo watch <id>     Watch combo progress live
agw version              Show version + check for updates
agw info                Show system information summary
agw queue               Show pending execution queue
agw export              Export tasks (--format csv -o file.csv)
agw mcp                Start MCP server (stdio transport for IDE integration)
agw daemon start|stop|status

Development

npm test          # Run 405+ tests
npm run build     # TypeScript compile
npm run dev       # Start dev server

Tech Stack

TypeScript, Fastify, SQLite (better-sqlite3), Commander.js, Pino, Node.js 22+

License

MIT