Orchestration
A lead orchestrator splits the task into roles and assigns each a model and skills. Sub-agents run by dependencies.
VOLY —
a flock of agents
Control plane for AI coding agents: multi-agent orchestration, a billing fallback chain, and cost control. Cheaper, more reliable, measurable.
9+
model providers
6
executors
5
roles in the flock
$0
re-run on cache hit
Fallback
Billing fallback chain: claude-code → wrangler → zen. Out of credits — the task doesn't fail.
Telemetry
Tokens, cost, and cache hits for every run. Spend limits, cost policy, and a savings report.
Open source
Apache 2.0, Python 3.10+. Project-agnostic: the target project is passed via --cwd.
How a task flies
One entry point — CLI, Web UI, or CI. From there, the route depends on task complexity.
voly run "implement auth refactor" --cwd /path/to/project
Multi-agent · A2A
The lead orchestrator assigns each role a model tier and skills. The flock flies by dependencies, passing results down the chain.
Executor · fallback chain
claude-code
Anthropic
✗ billing
wrangler
Workers AI
✗ billing
zen
free
✓ running
Out of billing — the next executor in the chain picks up the task. All three write files into --cwd.
AIGateway.chat()
the only exit to models
DLP
Cache
Rate limit
Spend limit
Provider
Telemetry
Executors
Who runs the task and what happens when billing runs out.
| Executor | Writes files | Billing | In the chain |
|---|---|---|---|
| claude-code | yes | Anthropic | 1st |
| wrangler | yes | CF Workers AI | 2nd |
| zen | yes | free | 3rd |
| cursor | yes | Cursor | standalone |
| opencode | yes | opencode.ai | standalone |
| deepseek / mimo | no — text only | API | outside the chain |
Savings you can see
VOLY counts every token: caching, routing, and fallback turn into concrete numbers, not gut feelings.
voly savings
spent today
$4.20 / $20.00 limit
cache hits
62% → saved $6.85
model routing
premium → cheap: $3.10
task re-runs
8 tasks from cache: $0.00
total this week
saved $41.70
* example output — numbers depend on your tasks
Quick start
A full control plane running locally in a couple of minutes. Requires Python 3.10+ and API keys in .env.
git clone https://github.com/voly-codes/voly.git && cd voly
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[ui,dev]"
voly init && voly ui
# then — the dashboard at localhost:7788
Orchestration
A complex task never goes to a single agent — it is decomposed into roles, each executed by a model of the right tier.
- TaskDecomposer splits the task: architect → developer → tester → reviewer → devops.
- The lead orchestrator (a premium model) assigns each role a tier — premium, standard, or cheap — plus skills from the registry.
- A tier resolves to a concrete model from a live pool: providers are filtered by a health checker.
- Role outputs flow down the chain; assignments and cost are visible in the Web UI.
voly run "implement auth refactor" --cwd /path/to/project
Fallback
When the current executor runs out of money, VOLY automatically hands the task to the next one in the chain.
- The chain: claude-code (Anthropic) → wrangler (CF Workers AI) → zen (free).
- billing_error = true → next executor; all three write files into --cwd.
- Inside the AI Gateway: model-level fallback and provider health checks.
- Sub-agents are deterministic (temperature = 0) and the cache is persistent: re-running the same task costs $0.
voly status
Telemetry
Every run leaves a TaskEvent: who executed it, which model, how many tokens, and how much money.
- A daily spend limit and a per-task cost policy keep spending under control.
- Gateway pipeline: DLP → Cache → Rate limit → Spend limit → Provider → Telemetry.
- Analytics in the Web UI: daily, by_agent, by_model, by_provider.
- voly savings shows how much caching and routing saved.
voly savings
Open source
VOLY is not yet another agent — it is an open control plane between the developer and the agents.
- Wraps Claude Code, Cursor, Codex, Zen, OpenCode, and more.
- Providers: Anthropic, OpenAI, Google, DeepSeek, Workers AI, Cloudflare AI Gateway.
- DSPy as an optional optimization layer: off / shadow / active.
- Web UI in Svelte 5: tasks, gateway, telemetry, multi-agents.
pip install -e ".[ui,dev]" && voly init