01
Developer
Delegates code safely
Runs familiar agents through one CLI, previews the diff with dry-run, protects secrets, and limits how many files a task may touch.
Outcome: less risk to the working repository
CONTROL PLANE FOR AI CODING AGENTS
v0.1.0 · available on PyPI ↗Agents write code.
VOLY runs the work.
Bring Claude Code, Codex, Cursor, and other tools into one managed process. VOLY routes hybrid multi-agent work, blocks text-only “done”, protects file changes, and tracks cost.
- a provider failure does not kill the task
- a confident summary without files is not success
- roles, files, verify, and cost land in one report
WHY ADD A CONTROL LAYER
When one agent is no longer enough
A direct agent run is great for a one-off task. Daily development also needs recovery, guardrails, and evidence that the work is actually done.
×Credits run out and the task stops
✓VOLY switches executor and continues the run
×The agent says it is done — with zero files
✓Executor honesty + plan gates: files, git diff, scoped tests
×Nobody knows exactly what changed
✓The run report stores roles, files, diff, and outcome
×A premium model handles every step
✓Routing assigns the right model tier to each role
×Spend is scattered across providers
✓Tokens, cache hits, and cost share one telemetry trail
×The agent rewrites code that already exists
✓voly reuse finds proven GitHub code: search → pack → pick → apply
×An imported skill or agent might quietly make things worse
✓Capabilities activate only after a measured pilot — no evidence, no routing
×A custom UI can't plug into a one-off event format
✓AG-UI protocol streams every run over SSE — any compatible frontend can subscribe
×A subtask can only run on the machine you're sitting at
✓A2A federation delegates it to another agent worker, tracked by task ID, safe to retry
×An LLM judge that always agrees with itself proves nothing
✓Golden regression replay plus judge-vs-human calibration measure false-pass and false-fail rates
×Reusing GitHub code means checking every license by hand
✓voly reuse searches, packs, and applies — GPL and AGPL are blocked by policy before code lands
ONE CONTROL PLANE — THREE LEVELS
Who VOLY helps
Start locally on your own. Add orchestration and team Cloud as the workflow grows.
02
Tech lead
Splits complex work into accountable roles
Architect, developer, tester, and reviewer get separate models and checks. A step advances only after its result is verified.
Outcome: a managed chain instead of one giant prompt
03
Team
Shares the complete picture
Linked local agents and hosted sandbox runs share one organization timeline: members, spend, status, and results in the Cloud dashboard.
Outcome: visibility without moving daily compute off the laptop
How a task flies
One entry point — CLI, Web UI, or CI. From there, the route depends on task complexity. Evidence gates block “done” without files or tests.
voly run "implement auth refactor" --cwd /path/to/project
Multi-agent · hybrid A2A
Architect / reviewer on chat; developer / tester / devops write via executors. Git-diff evidence + plan verify — no success on a text-only summary.
Executor · fallback chain
claude-code
Anthropic
✗ billing
cursor
Cursor
✗ billing
deepseek
DeepSeek
✗ billing
zen
last resort
✓ running
Out of billing — the next file-capable executor picks up. Full chain: claude-code → cursor → deepseek → wrangler → opencode → zen. Preview with --dry-run.
AIGateway.chat()
sole exit for chat models · executors are a separate path
DLP
Cache
Rate limit
Spend limit
BYOK
Provider
Telemetry
ONE TASK — ONE REPORT
A verifiable run, not a promise
How VOLY beats multi-agent hallucinations: status follows evidence on disk — not a polished summary. Illustrative report reading.
TaskDesign PulseBoard API, implement CRUD + JWT, tests, review, Compose/CI
✓ verified
architect
chat plan · cloudflare-dynamic
✓ verified
developer
executor · 44 files · cursor
✓ verified
tester
executor · 5 files · 56 pytest
✓ verified
reviewer
chat · git-diff evidence
✓ verified
devops
executor · Compose + CI
53files
56tests
$0.013telemetry*
completedoutcome
* Telemetry sum from a live greenfield run; Cursor usage is estimated. Status stays partial if any implement role writes zero files.
CHOOSE YOUR RUNTIME
Direct agent, VOLY Local, or Cloud
The open core is complete locally: orchestration, safety, executor chain, and cost control. Cloud is the team control plane — link, limits, shared history — plus an optional hosted sandbox from the browser.
| Capability | Direct agent | VOLY Local | VOLY Cloud |
|---|---|---|---|
| File-capable execution | yes | yes | yes |
| Multi-agent orchestration | — | yes | yes |
| Evidence gates (anti-hallucination) | — | yes | yes |
| Plan gates and safety policy | — | yes | yes |
| Billing fallback and cost report | — | yes | yes |
| Shared team history | — | — | yes |
| Roles, invites, and hosted runs | — | — | yes |
LOCAL
Local — keep control in your environment
Apache 2.0 on a laptop or your infra: full agent chain, your keys, your repositories. Cloud only links the agent and records runs.
Install Local →CLOUD
Cloud — one operating surface for the team
Organization, members, one history for local and hosted runs, spend limits, org BYOK aliases, and a browser hosted sandbox (probe today; fuller agent mode next).
Open Cloud ↗Local run report & team cloud
Open-core Web UI in action: a multi-agent run from dispatch to report — safety badges, hybrid role summary, touched files, dry-run diffs, tokens and cost. For the whole team: cloud.voly.codes shows shared org history, spend today, and hosted “Run in cloud”.
Orchestration
Hybrid flock: developer / tester / devops write files via executors; architect / reviewer stay on chat. Tiers and skills per role.
Anti-hallucination
A plausible summary is not a merge. Files on disk, git diff, and tests decide — not the agent’s self-report.
Safety
File writes are guarded: dry-run with diff preview, protected paths, max-files limit, git-based rollback.
Fallback
Billing fallback: claude-code → cursor → deepseek → wrangler → opencode → zen. Out of credits — the task keeps going.
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, spend, and a hosted sandbox — features stay open; pay for hosting.
Evidence-gated capabilities
Imported skills and agents activate by measured evidence, not by installation. No paired pilot, no routing — ever.
AG-UI protocol streaming
Every run streams over the open AG-UI protocol (CopilotKit) — text, tool calls, and state over SSE. Any compatible frontend can subscribe, not only VOLY's own UI.
A2A federation
Subtasks aren't stuck on your machine. Delegate to another agent worker over Cloudflare — tracked by task ID, idempotent, safe to retry.
Evaluation engine
Deterministic policies per task type, an optional rubric-based LLM judge, and golden-dataset regression replay — plus calibration that measures whether the judge itself can be trusted.
GitHub code reuse
voly reuse searches GitHub, packs the structure, picks the modules, and applies them — GPL and AGPL are blocked by license policy before anything lands in your repo.
MCP server
Run VOLY from any MCP host — Cloudflare OS, Claude Desktop, your IDE. Reads answer instantly; anything that spends money asks a human first.
Executors
Who runs the task and what happens when billing runs out.
| Executor | Writes files | Billing | In the chain |
|---|---|---|---|
| claude-code | yes | Anthropic | 1st |
| cursor | yes | Cursor | 2nd (hybrid default) |
| deepseek | yes | DeepSeek API | 3rd |
| wrangler | yes | CF Workers AI | 4th |
| opencode | yes | opencode.ai | 5th |
| zen | yes | free / subscription | 6th (last resort) |
| cf-containers | yes | CF Containers | outside the chain |
| mimo | limited | API | outside the chain |
Skill & Plugin Marketplace
Install domain knowledge packs that agents use automatically. Skills teach methodology; plugins bundle tools. One command to install, active on the next run.
Find a skillGit packages
Multi-file skill packages (like PMBOK 6, design systems, company playbooks) install via git clone and are picked up instantly.
Lazy discovery
The lead orchestrator surfaces relevant skills from the marketplace mid-run — you see what's available for your specific task, not a generic catalogue.
One-click install
Install directly from the run result banner. The skill is active on the next run — no restart needed.
Live in marketplace:
— skills
— plugins
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
See what VOLY can run — before installing it
Run a read-only preflight against your repository with Python 3.10+. It checks the project, configuration, and available local executors without writing files or launching an agent.
uvx --from voly==0.1.0 voly quickstart --check --cwd .
# no repository writes · no agent launch · no permanent install
Higher together
Run the full open-core agent on your machine — then invite the team on cloud.voly.codes for shared history and hosted sandbox.
Orchestration
A complex task never goes to a single agent — it is decomposed into roles, each on the right model tier (hybrid multi-agent).
- TaskDecomposer splits the task: architect → developer → tester → reviewer → devops.
- lead_mode=auto skips a premium lead chat on standard role sets; tiers still resolve from a healthy provider pool.
- With --cwd, hybrid runs developer / tester / devops through file-capable executors; architect and reviewer stay on AIGateway.chat().
- Prior outputs plus git-diff evidence are passed forward so review and tests see real code, not a story.
- Tech stack gate: pin framework versions before the run (registry + runtime preflight); an empty cwd gets a category picker and greenfield scaffolding.
- voly reuse: GitHub search → pack → pick → apply lands proven code before agents write from scratch — optionally auto-searched before every executor call.
- Role mode, cost, files, and plan verify land in the CLI summary and Web UI run report.
voly run "implement auth refactor" --cwd /path/to/project
Anti-hallucination
Multi-agent runs used to “complete” when Cursor wrote a confident summary and zero files. VOLY treats that as failure, not success.
- Executor honesty: on code-gen, success with files_touched=0 → role failed, run status partial — never a fake completed.
- Plan gates verify steps with git_diff_nonempty, files_exist, and scoped pytest — shadow or active.
- Reviewer and tester receive git-diff evidence from prior roles, not only prose context.
- files_touched counts as real work so a soft safety rollback does not cascade-skip the rest of the flock.
- Deterministic sub-agents (temperature=0) and a persistent gateway cache make retries cheap and repeatable.
voly run "redesign auth, add tests, review" --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 hits a billing or not-available error, VOLY walks the file-capable chain automatically.
- Chain: claude-code → cursor → deepseek → wrangler → opencode → zen (last resort).
- Hybrid defaults: developer/tester/devops → cursor; bugfixer → deepseek (override with VOLY_A2A_EXECUTOR_<ROLE>).
- billing_error / not_available → next executor; every hop still writes under --cwd.
- AIGateway keeps model-level fallback and provider health (exclude via VOLY_A2A_EXCLUDE_PROVIDERS).
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): orgs & invites, Clerk SSO, device-code agent link, revoke, shared local+hosted history, spend, BYOK, Run in cloud.
- Linked laptop reports finished runs into the org timeline; revoke blocks further heartbeats and reports.
- 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
Evidence-gated capabilities
Every imported skill, hook, or agent is an untrusted candidate until it clears a paired production pilot against native VOLY routing — reputation and defaults do not activate anything.
- Lifecycle: discover → static admission → quarantine/stage with provenance → paired production pilot → held-out validation → activate within quality/token/latency bounds, or retire.
- Real pilot results so far: tdd-workflow.v1 measured +0.20 quality lift and stayed active; security-reviewer.v1 measured 0.00 added value and was retired automatically.
- Retirement is automatic once the minimum sample count is reached — no manual pruning of capabilities that quietly add nothing.
- Research, memory, and learning stay opt-in: shadow reuse/adapt/build recommendations, typed strategic memory, and instincts that need positive evidence plus manual approval before they run.
- Lifecycle hooks stay harness-neutral, disabled by default, and limited to built-in allowlisted handlers — never arbitrary imported code.
- DSPy is available as an optional optimization layer (off / shadow / active) on top of the same evidence pipeline.
voly capability evaluated activate security-reviewer
AG-UI protocol streaming
VOLY doesn't just render its own dashboard — it speaks the AG-UI standard, so any compatible frontend can subscribe to a live run.
- Standard event vocabulary: TEXT_MESSAGE_START/CONTENT/END, TOOL_CALL_START/ARGS/END/RESULT, STATE_SNAPSHOT/DELTA, RUN_STARTED/FINISHED/ERROR.
- AGUI_START opens the SSE stream at pipeline entry; AGUI_DONE closes it once the run finishes — every stage in between can emit events.
- A remote client forwards events to a Cloudflare AGUISession Durable Object, so a run started on one machine can be watched from anywhere.
- Same protocol used by CopilotKit-based frontends — build your own UI on a run instead of parsing VOLY-specific output.
voly agui start --port 9101
A2A federation
Local hybrid multi-agent covers one machine. A2A federation extends the same role model across Cloudflare Worker-hosted agents.
- Federation worker exposes POST /tasks (create + queue dispatch), GET /tasks/:id (status), and POST /tasks/:id/complete (agent callback).
- Callbacks and queue dispatch are idempotent: completing an already-completed task is a no-op, and the queue skips dispatch once state has moved past submitted.
- The remote agent worker checks task state before re-executing, so a retried delegation never reruns a task that already finished or failed.
- --a2a-delegate forces the federated path explicitly; auto-dispatch takes it without the flag once a2a.enabled and the task looks complex enough.
voly a2a call developer "implement OAuth2 login" --remote
Evaluation engine
Passing an LLM judge is not proof of quality on its own — VOLY tracks whether the judge agrees with humans, not just whether it approves.
- Built-in policies by task type (documentation, testing, security, executor-basic) require executor success, a clean bounded trajectory, at least one retained file change, and successful replay of every baseline command.
- Security tasks additionally require a diff-scoped static scan (hardcoded secrets, unsafe eval/subprocess/YAML) plus explicit human review; documentation tasks require valid link destinations plus human review.
- An optional rubric-based LLM judge scores versioned dimensions per task type — a critical dimension below 2/4 fails the check even if the weighted score would pass.
- voly eval calibrate aggregates human-vs-judge feedback into a confusion matrix with a 95% Wilson interval, false-pass rate, and false-fail rate, per policy/rubric/model lineage.
- Golden datasets (schema v1) replay typical, edge, and adversarial cases offline against a candidate implementation for controlled regression comparisons.
voly eval calibrate --min-samples 20
GitHub code reuse
Writing auth middleware or a rate limiter from scratch is usually re-solving a problem someone already shipped under a permissive license.
- Pipeline: task → QueryPlanner or keyword query → GitHub Search API → star + license filter → shallow clone → structure pack → ModulePicker → apply under a dry-run by default.
- License gate is config, not a suggestion: allowed_licenses (mit, apache-2.0, bsd, isc, unlicense, …) and deny_licenses (gpl-2.0/3.0, agpl-3.0) run before any file is copied.
- voly reuse search finds candidates; voly reuse pack/pick narrows to modules; voly reuse apply --write is the only step that actually writes files.
- reuse.auto can run search + pick automatically before every executor call, capped by auto_max_repos and a freshness window so it doesn't repeat work every run.
voly reuse run "add rate limiter" --cwd /path/to/project --lang python
MCP server
`voly mcp serve` exposes the orchestrator as nine MCP tools, so a host you already work in can start runs and follow them — no second UI to build.
- Six read tools (runs, tasks, spend, provider health) resolve immediately and are recorded as observations.
- voly_start_run is annotated destructive and non-idempotent, so a host always asks a human before it spends credits and writes files.
- A run outlives a tool call: start returns a task_id at once, voly_get_run polls the heartbeat, voly_get_task reads the result.
- Provider keys never cross the boundary — the host bills its own inference, VOLY bills its own; only tasks and results move.
- Streamable HTTP transport; narrow a grant to specific tools with #tool= on the endpoint URL.
voly mcp serve --port 7799