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. Run open-core locally — or team cloud at cloud.voly.codes.
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 + Cloud
Apache 2.0 core on your laptop. Team cloud is live: orgs, invites, shared run history, hosted runs, spend — features stay open, hosting is paid.
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
Local run report & team cloud
Open-core Web UI: every run opens into a report — safety badges, hybrid role summary, touched files, dry-run diffs, pxpipe prompt images, tokens and cost. For the whole team: cloud.voly.codes shows shared org history, spend today, and hosted “Run in cloud”.
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, fallback, and pxpipe text→image compression 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
pxpipe artifacts
prompt images saved per task
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 pxpipe start # optional: token-saving Claude Code proxy
voly run "fix a bug" --cwd ~/my-project --dry-run
# local dashboard at localhost:7788 — team cloud at cloud.voly.codes
Higher together
Build and run agents open-core on your machine — or invite the team on cloud.voly.codes.
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, how much money, and which local artifacts were produced. 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), local task artifacts, and voly savings.
- pxpipe can route Claude Code through a local token-saving proxy and save rendered prompt PNGs into the task report.
- voly savings shows how much caching, routing, fallback, and compression saved.
voly savings
Open core + Cloud
VOLY is not yet another agent — it is an open control plane between the developer and the agents.
- Open core (public repo): orchestration, hybrid multi-agent, fallback chain, safety policy, FinOps, local CLI + Web UI, BYOK in your Cloudflare account.
- Cloud (live MVP at cloud.voly.codes): register/login, orgs & invites, shared org run history (local + hosted), spend rollup, BYOK aliases, Run in cloud.
- Local agent can report finished runs to the org when linked — one team timeline, compute stays on the laptop if you want.
- Wraps Claude Code, Cursor, Codex, Zen, OpenCode, and more under --cwd.
- Providers: Anthropic, OpenAI, Google, DeepSeek, Workers AI, Cloudflare AI Gateway. Contributions via DCO.
pip install -e ".[ui,dev]" && voly init