Orchestration
A lead orchestrator splits the task into roles and assigns each a model and skills. Implement roles write files; review stays on chat.
VOLY —
a flock of agents
Control plane for AI coding agents: multi-agent orchestration, plan gates, write-safety (dry-run & protected paths), a billing fallback chain, and cost control. Cheaper, safer, measurable.
9+
model providers
7
executors
5
roles in the flock
$0
re-run on cache hit
Plan gates
Steps only advance after verification — files, git, or tests. Not “the model said it was done.”
Safety
File writes are guarded: dry-run with diff preview, protected paths, max-files limit, git-based rollback.
Fallback
Billing fallback chain: claude-code → wrangler → opencode → zen. Out of credits — the task doesn't fail.
Telemetry & BYOK
Tokens, cost, and cache hits per run. Spend limits, cost policy — and provider keys in Cloudflare Secrets Store.
Open core
Apache 2.0, Python 3.10+. Full control plane locally — cloud sells teams and hosting, not core features.
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 · hybrid A2A
The lead assigns tiers and skills. Implement roles write files via executors; review stays on chat. Results and cost flow into one run report.
Executor · fallback chain
claude-code
Anthropic
✗ billing
wrangler
Workers AI
✗ billing
opencode
free models
✗ billing
zen
free
✓ running
Out of billing — the next executor in the chain picks up the task. Every one of them writes files into --cwd. Use --dry-run to preview writes safely.
AIGateway.chat()
the only exit to models
DLP
Cache
Rate limit
Spend limit
BYOK
Provider
Telemetry
Run report & live dashboard
Every run opens into a report: safety badges, hybrid role summary, touched files, dry-run diffs, tokens and cost. Multi-agent assignments show which role ran on which model. CLI tasks appear while still in flight.
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 |
| opencode | yes | free models → your own keys | 3rd |
| zen | yes | free | 4th (last resort) |
| cursor | yes | Cursor | 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. Python 3.10+. Keys via .env or BYOK in Cloudflare Secrets Store.
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
voly run "fix a bug" --cwd ~/my-project --dry-run
# dashboard at localhost:7788 — try --dry-run before a real write
Orchestration
A complex task never goes to a single agent — it is decomposed into roles, each executed by a model of the right tier (hybrid multi-agent).
- 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.
- Hybrid path: implement roles run file-capable executors under --cwd; reviewer and chat roles stay on AIGateway.
- A tier resolves to a concrete model from a live pool: providers are filtered by a health checker.
- Role outputs, cost, and files land in the run report in the Web UI — including live CLI tasks while they run.
voly run "implement auth refactor" --cwd /path/to/project
Plan gates
Good plans are not enough if the agent freestyles. VOLY turns a plan into a state machine with hard gates.
- Each step has a status: pending → running → verified (or failed).
- The next role starts only after prior steps are verified — evidence over self-report.
- Acceptance checks: command, files_exist, git_diff, output — fail closed on unknown types.
- Modes: shadow (log and soft-open) or active (hard gate). Multi-agent A2A can use the same rules.
- CLI: voly plan run | criteria | suggest — draft checks from free text or ProjectScanner.
voly plan run plan.yaml --mode active --cwd /path/to/project
Safety
Letting an agent write into a real repo needs a safety net — VOLY ships one in the open core.
- --dry-run runs the full executor path, then rolls changes back and keeps a diff preview in the result.
- Protected paths block writes to secrets and env files (.env*, keys, credentials) by policy.
- Max-files limit stops a runaway agent from touching half the monorepo in one run.
- Touched files are detected from content (not only git dirty-before), so clean tracked files modified mid-run still show up.
- The Web UI run report surfaces safety badges, hybrid summary, files, and dry-run diffs.
voly run "refactor the config loader" --executor claude-code --cwd ~/my-project --dry-run
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) → opencode (free models) → zen (free).
- billing_error = true → next executor; every executor in the chain writes 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 & BYOK
Every run leaves a TaskEvent: who executed it, which model, how many tokens, and how much money. Keys do not have to live in every machine’s .env.
- A daily spend limit and a per-task cost policy keep spending under control.
- Gateway pipeline: DLP → Cache → Rate limit → Spend limit → Provider → Telemetry.
- BYOK: store provider keys in Cloudflare AI Gateway / Secrets Store; the gateway resolves them per request.
- Web UI: Provider keys page, analytics (daily, by_agent, by_model, by_provider), and voly savings.
- voly savings shows how much caching, routing, and fallback saved.
voly savings
Open core
VOLY is not yet another agent — it is an open control plane between the developer and the agents.
- Open core (this repo): orchestration, hybrid multi-agent, fallback chain, safety policy, FinOps, local CLI + Web UI, BYOK in your Cloudflare account.
- voly-cloud (commercial, later): auth/SSO, teams, hosted runs, shared org history and spend — not a locked-down core.
- Wraps Claude Code, Cursor, Codex, Zen, OpenCode, and more under --cwd.
- Providers: Anthropic, OpenAI, Google, DeepSeek, Workers AI, Cloudflare AI Gateway.
- Open, versioned protocols (TaskEvent, spend) — integrate without forking. Contributions via DCO.
pip install -e ".[ui,dev]" && voly init