{
  "markdown": "<p align=\"center\">\n  <a href=\"https://github.com/voly-codes/voly/actions/workflows/ci.yml\"><img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/voly-codes/voly/ci.yml?branch=main&style=for-the-badge\"></a>\n  <a href=\"https://pypi.org/project/voly/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/voly?style=for-the-badge&logo=pypi&logoColor=white\"></a>\n  <img alt=\"Python\" src=\"https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white\">\n  <img alt=\"Multi-Agent\" src=\"https://img.shields.io/badge/Multi--Agent-A2A-6366F1?style=for-the-badge\">\n  <img alt=\"DSPy\" src=\"https://img.shields.io/badge/DSPy-Optional-22C55E?style=for-the-badge\">\n  <img alt=\"Cloudflare AI Gateway\" src=\"https://img.shields.io/badge/Cloudflare-AI_Gateway-F38020?style=for-the-badge&logo=cloudflare&logoColor=white\">\n  <img alt=\"AG-UI\" src=\"https://img.shields.io/badge/AG--UI-Streaming-0EA5E9?style=for-the-badge\">\n  <img alt=\"License\" src=\"https://img.shields.io/badge/License-Apache_2.0-orange?style=for-the-badge\">\n</p>\n\n<p align=\"center\">\n  AI Agent Control Plane · Evidence-Governed Capabilities · Multi-Agent Orchestration · FinOps · A2A · AG-UI · Cloudflare\n</p>\n\n<p align=\"center\">\n  <strong>English</strong> · <a href=\"README_ru.md\">Русский</a>\n</p>\n\n# VOLY — Control Plane for AI Agents\n\n> **VOLY wraps Claude Code, Cursor, DeepSeek, OpenCode/Zen and other AI agents so you can run them cheaper, safer, and with full measurability.**\n\nVOLY is not another AI agent. It is a **self-hosted control plane** between the developer and the agents:\n\n- **routes** tasks across file-capable executors with an automatic billing fallback chain;\n- **decomposes** complex work into sub-agents (architect → developer → tester → reviewer → devops) with per-role model tiers; with `--cwd`, **hybrid** runs implement roles (developer / tester / devops) via executors and keeps architect / reviewer on chat;\n- **guards file writes** — dry-run with diff preview, protected paths (`.env*`, keys; `.env.example` allowlisted), soft rollback, max-files limit, git-based rollback;\n- **controls spend** via Cloudflare AI Gateway, spend limits, and cost policy;\n- **reduces tokens** with a persistent cache, Headroom, model routing, and determinism;\n- **reuses proven code** — `voly reuse`: GitHub search → pack → pick → apply, with optional auto-search before every executor run ([docs/backend/reuse.md](docs/backend/reuse.md));\n- **pins the tech stack** — pre-run version selection (framework registry + runtime preflight), category picker and greenfield scaffolding for empty projects;\n- **verifies** multi-agent steps with plan gates (shadow/active; scoped pytest when possible);\n- **evaluates outcomes** with deterministic policies, golden regression replay,\n  optional rubric-based LLM judges, human review, and privacy-safe evidence;\n- **adopts external capabilities safely** — discover → scan → quarantine →\n  stage with provenance → paired/held-out evaluation → activate or retire;\n- **learns conservatively** through research-first shadow decisions, compact\n  strategic memory, evidence-gated instincts, and constrained lifecycle hooks;\n- **collects telemetry** per run (CLI role summary + Web UI);\n- supports **DSPy** as an optional optimization layer;\n- stays **project-agnostic** — the target project is passed via `--cwd` or `VOLY_PROJECT_CWD`.\n\n## Why VOLY, and not just a single agent?\n\nClaude Code, Cursor, DeepSeek, and OpenCode are excellent **executors**. VOLY is the layer\n**above** them — it exists because running agents daily raises questions a\nsingle CLI cannot answer:\n\n| The question | VOLY's answer |\n|---|---|\n| The agent ran out of credits mid-task | Billing fallback `claude-code → cursor → deepseek → wrangler → opencode → zen` |\n| What did this run actually cost? | Per-run `TaskEvent`: cost, tokens, retries, per-role mode/files/verify in CLI + UI |\n| A complex task = one giant prompt? | Multi-agent + hybrid: developer/tester/devops write files; architect/reviewer stay on chat |\n| Is it safe to let an agent write files? | Safety: `--dry-run`, protected paths, soft rollback (keep other files), max-files, git rollback |\n| A premium model for a routine fix? | Cost policy + tier routing (Anthropic last among paid peers; exclude via env) |\n| Provider keys in `.env` on every machine? | BYOK: keys in Cloudflare Secrets Store, resolved by the gateway per request |\n| Should an imported skill become active? | Paired baseline/variant evidence, held-out checks, token/latency bounds, explicit activation or retirement |\n| Can the system learn without silently rewriting prompts? | Shadow research, scoped strategic memory, manually approved instincts, allowlisted hooks |\n\nIf all you need is \"write code from a prompt\" — use an agent directly. VOLY\npays off when agents become part of the **daily workflow** and you need\neconomics, control, and reports.\n\n## Quick demo\n\n```bash\nuvx --from voly==0.1.0 voly quickstart --check --cwd ~/my-project\n# → offline, read-only preflight: repository, config, local executors, safe next command\n\nvoly init                                   # config + hooks\nvoly run \"fix the auth redirect bug\" \\\n    --executor claude-code --cwd ~/my-project\n# → the executor writes files; if it hits a billing error the chain\n#   falls through to the next executor; cost and touched files land\n#   in the run report\n\nvoly run \"refactor the config loader\" \\\n    --executor claude-code --cwd ~/my-project --dry-run\n# → same run, but every file change is rolled back afterwards;\n#   the diff preview is kept in the result\n\nvoly ui                                     # web dashboard on :7788\n```\n\nOr from Python — a governed chat call in under ten lines, no provider client\ninvolved (DLP/spend/cache/fallback apply exactly as they do for `voly run`):\n\n```python\nfrom voly import Agent, Workflow\n\nresearcher = Agent(\"researcher\", instructions=\"Find verifiable facts\")\nreviewer = Agent(\"reviewer\", instructions=\"Check claims and sources\")\n\nworkflow = Workflow(\"research-review\")\nworkflow.add(\"research\", agent=researcher)\nworkflow.add(\"review\", agent=reviewer, depends_on=[\"research\"])\n\nresult = workflow.run(\"Compare two markets\")\nprint(result.success, result.cost_usd, result.node(\"review\").output)\n```\n\n`Workflow.add(..., approval=True)` gates a node behind human sign-off — the\nrun pauses (never \"fails\") until `voly.plan.approval.decide()` approves it.\nIndependent nodes run in bounded concurrent waves\n(`workflow_sdk.max_parallel_nodes`); a run survives a process restart via\n`workflow.resume(plan_id)`, and `workflow.cancel(plan_id)` stops one in\nflight from elsewhere.\n\nSix reusable graph factories build a `Workflow` for you — no manual\n`.add()` wiring:\n\n```python\nfrom voly import Agent, council\n\nresult = council(\n    [Agent(\"bull\"), Agent(\"bear\")], Agent(\"judge\"),\n).run(\"Should we invest in this market?\")\n```\n\n`sequential`, `concurrent`, `supervisor_workers`, `reviewer_loop`, `council`\nand `planner_generator_evaluator` are also available — see\n[docs/backend/sdk.md](docs/backend/sdk.md) for the full contract, node-id\nshapes and bounds. CLI/API/UI surfaces are the next phase\n(`docs/proposals/agent-workflow-sdk.md`).\n\nFor an installed package, use `voly quickstart --cwd ~/my-project`. Add `--yes`\nto create a missing `voly.yaml` without prompting. Quickstart never installs or\nlaunches a third-party agent; its suggested first run uses `--dry-run`.\n\nA complex request (\"redesign auth, add tests, review it\") goes multi-agent\nautomatically (`lead_mode=auto` skips a premium lead chat on standard role\nsets). With `--cwd`, hybrid implement roles write files; architect/reviewer\nstay on chat — the report shows role / mode / cost / files / verify.\n\n### Recorded demo: 3D voxel tanks built by a multi-agent chain\n\nA single task (\"build a 3D voxel tank game\") dispatched through VOLY to a\ndeveloper → tester → reviewer chain. The recording captures the result from\nthat run; it is a product demonstration, not a current performance or cost\nbenchmark.\n\n<p align=\"center\">\n  <a href=\"https://github.com/voly-codes/voly/releases/download/demo-voxel-tanks/export-1784466924338-compact.mp4\"><img src=\"docs/assets/video-preview.webp\" alt=\"Watch the demo\" width=\"900\"></a>\n</p>\n\n## Open core vs Cloud\n\n| | **voly** (this repo, Apache-2.0) | **voly-cloud** (commercial) |\n|---|---|---|\n| Orchestration, multi-agent, hybrid executors | ✔ full | same core |\n| Billing fallback chain, cost policy, telemetry | ✔ full | same core |\n| Executor safety policy (dry-run, protected paths) | ✔ full | same core |\n| Local Web UI + CLI, self-hosted, single tenant | ✔ | — |\n| BYOK in **your** Cloudflare account | ✔ | managed per tenant |\n| Auth / SSO / teams / audit | — | ✔ |\n| Hosted runs, shared spend dashboards, org limits | — | ✔ |\n\nThe open core is complete and self-hosted. The paid tier sells hosting and\nteam management — not core features.\n\n## How it works\n\nA task from the web UI, CLI, or CI enters a single entry point and takes one of two paths:\n\n```text\nDeveloper / Web UI / CLI / CI\n              ↓\n       VOLY Entry Point\n              ↓\n        ROUTE (task analysis)\n        ┌─────┴───────────────────────────┐\n        │                                 │\n   complex,                         simple code\n   ≥2 capabilities                  generation (1 flag)\n        │                                 │\n        ▼                                 ▼\n  PIPELINE · MULTI-AGENT            EXECUTOR PATH\n  (A2A local + hybrid)              (file-capable)\n        │                                 │\n  Decompose + tier/skills           executor.run(task, cwd)\n   ├─ architect / reviewer          Billing Fallback Chain:\n   │    → AIGateway.chat()          claude-code → cursor → deepseek →\n   ├─ developer / tester / devops     wrangler → opencode → zen\n   │    → AgentRunner (files)               │\n   └─ plan gates + merge report             │\n        │                                   │\n        └──────────────┬────────────────────┘\n                       ▼\n         chat roles → AIGateway.chat()\n         DLP → Cache → Rate/Spend → Provider → Telemetry\n                       │\n                       ▼\n       Evidence → Evaluation → Capability learning\n```\n\nNon-code-generating text tasks go through a single model call on the same pipeline path.\n\n**`AIGateway.chat()`** is the only exit to **models** (pipeline chat roles, DSPy, runtimes). File-capable **executors** are a separate path (CLI/SDK subprocesses) with their own billing fallback.\n\n**Smart dispatch** (`POST /api/run`, `executor=pipeline`):\n\n- complex multi-capability task (≥ `a2a.min_flags_for_dispatch` flags from code-gen / review / testing / deployment, or `complexity=high`) → **stays in the pipeline and runs multi-agent**;\n- simple code task → promoted to `executor=claude-code` with `cwd` from config / `VOLY_PROJECT_CWD` (so files are actually written);\n- text task → single model call.\n\n## Multi-agent orchestration (A2A local)\n\nWhen a task enters multi-agent mode (`a2a.execution_mode=local`, default):\n\n1. **`TaskDecomposer`** splits the task into roles with dependencies (architect → developer → tester → reviewer → devops).\n2. **Lead orchestrator** — assigns each role a **model tier** (`premium | standard | cheap`) and **skills** (`lead_mode=auto` skips the LLM lead on standard role sets). On lead failure — deterministic fallback with role-aware skill relevance.\n3. Tier → concrete `(model, provider)` from a **live pool** filtered by `ProviderHealthChecker` (Anthropic last among paid peers).\n4. With `--cwd`, **hybrid** runs developer / tester / devops via file-capable executors; architect / reviewer stay on `AIGateway.chat()`. Prior outputs + git-diff evidence are passed forward.\n5. Merge → `TaskEvent` with `a2a_assignments` (role / mode / files / verify / cost). CLI prints a compact role summary; Web UI shows the Multi-agents panel.\n\n**Repeat savings:** sub-agents are deterministic (`temperature=0`), and the gateway cache is **persistent** (on disk). Skip a provider (e.g. out of credits): `VOLY_A2A_EXCLUDE_PROVIDERS=anthropic` (applied before the first chat call).\n\n## Quick start\n\nInstall the published package (Python 3.10+):\n\n```bash\npython -m pip install voly\nvoly --version\nvoly quickstart --check --cwd ~/my-project\n```\n\nFor a one-off run without a persistent installation:\n\n```bash\nuvx --from voly voly quickstart --check --cwd ~/my-project\n```\n\nThe universal Python wheel works on Windows, macOS, and Linux. Verified release\nartifacts and checksums are available on [GitHub Releases](https://github.com/voly-codes/voly/releases/latest); the package of record is on [PyPI](https://pypi.org/project/voly/).\n\n### Development installation\n\n```bash\ngit clone https://github.com/voly-codes/voly.git\ncd voly\npython3 -m venv .venv && source .venv/bin/activate\npip install -e \".[ui,dev]\"\ncp .env.example .env       # add API keys\nvoly init\nvoly status\n```\n\nWeb UI (dev):\n\n```bash\n# backend API (FastAPI) — :7788\npython3 -m uvicorn voly.web.server:create_app --factory --host 127.0.0.1 --port 7788\n# UI dev server (Vite) — :5173, proxies API to :7788\ncd ui && npm install && npm run dev\n```\n\nSingle process (production, serves the built UI on :7788):\n\n```bash\ncd ui && npm run build && cd ..\nvoly ui\n```\n\nPipeline runner for CF agent workers over a tunnel — separate service on `:9202`:\n\n```bash\nvoly serve\n```\n\nDSPy (optional):\n\n```bash\npython -m pip install \"voly[dspy]\"\n# Source checkout: pip install -e \".[dspy,dev]\"\nvoly dspy status\n```\n\n### Web UI auth (optional)\n\nBy default the API is **open on localhost**. Before exposing the UI/API on a network, enable JWT:\n\n```bash\nexport VOLY_AUTH_ENABLED=true\nexport VOLY_JWT_SECRET='long-random-secret-at-least-32-chars'\nexport VOLY_AUTH_USERS='admin:change-me'\n```\n\nSee [docs/backend/api.md](docs/backend/api.md) for login and protected routes.\n\n## Billing fallback chain (executor path)\n\nIf the current executor hits a billing / not-available error, `AgentRunner` walks:\n\n```\nclaude-code → cursor → deepseek → wrangler → opencode → zen\n(Anthropic)   (Cursor)  (DeepSeek)  (CF)      (OpenCode)  (last resort)\n```\n\n`ExecutorResult.billing_error = True` (or `not_available`) → next in chain. Hybrid defaults: developer/tester/devops → `cursor`, bugfixer → `deepseek` (override with `VOLY_A2A_EXECUTOR_<ROLE>`).\n\n## Executors\n\n| Executor | Writes files | Billing | Chain position |\n|---|---|---|---|\n| `claude-code` | yes — Claude CLI | Anthropic | 1st |\n| `cursor` | yes — Cursor Agent SDK | Cursor | 2nd (hybrid default for developer/tester/devops) |\n| `deepseek` | yes — DeepSeek file executor | DeepSeek API | 3rd (hybrid default for bugfixer) |\n| `wrangler` | yes — LocalPatchApplier | CF Workers AI | 4th |\n| `opencode` | yes — OpenCode CLI | opencode.ai | 5th |\n| `zen` | yes — opencode CLI | free / subscription | 6th (last resort) |\n| `mimo` | text / limited | API | outside chain |\n\n```bash\nvoly run \"implement auth refactor\" --executor claude-code --cwd /path/to/target-project\n```\n\nFor automatic selection use the Web UI or `voly match`.\n\n## AI Gateway\n\n`AIGateway.chat()` is the single model exit. Middleware: **DLP → Cache → Rate limit → Spend limit → Routing → Provider**.\n\n- **Persistent cache** — responses are stored on disk (`ai_gateway.cache_persist_dir`, default `.voly/gateway_cache`), so repeats hit cache across requests and restarts.\n- **Spend on success only** — failed provider calls do not inflate the daily budget.\n- **Providers**: `anthropic`, `openai`, `google`, `deepseek`, `workers-ai`, `cloudflare-dynamic`, `opencode-zen`, `mimo`, **`omniroute`** (self-hosted OpenAI-compatible gateway, opt-in).\n- **Gateway tab metrics** come from telemetry (real requests / tokens / cost / `by_provider` / `by_model` / `spent_today`), not a fresh empty instance.\n\nThe CF Worker (`cf-workers/agent/src/infer.ts`) routes inference through the CF AI Gateway route schema (`CF_ACCOUNT_ID` + `CF_AIG_TOKEN`, `POST /infer`) or `env.AI.run()` fallback.\n\n## Evidence-governed capability lifecycle\n\nVOLY treats agents, skills, rules, hooks, MCP configurations, and legacy\ncommand shims as **untrusted capability candidates**, not plugins that become\nactive when copied:\n\n```text\ndiscover → static admission → quarantine/stage → verify provenance\n        → paired production pilot → held-out validation\n        → activate within quality/token/latency bounds, or retire\n```\n\n- **Eval Engine** selects a versioned policy before execution and records\n  deterministic checks, bounded trajectory evidence, optional rubric-based LLM\n  judging, and explicit human review. Golden datasets replay typical, edge, and\n  adversarial cases offline.\n- **External packs** are discovered without importing code. Staged components\n  retain source revision, license, checksums, compatibility aliases, and\n  quarantine decisions; installation never activates them.\n- **Evaluated packs** route only after measured evidence. The bundled pilot\n  covers `security-reviewer`, `tdd-workflow`, and `python-reviewer`; native VOLY\n  routing remains the fallback.\n- **Research, memory, and learning** are opt-in. Research produces shadow\n  `reuse | adapt | build` recommendations, strategic memory injects bounded\n  typed records without deleting raw history, and instincts require positive\n  evidence plus manual approval.\n- **Lifecycle hooks** are harness-neutral, disabled by default, and limited to\n  built-in allowlisted handlers—never arbitrary imported Python or shell\n  callbacks.\n- **Cloudflare sync** publishes an authenticated, immutable capability-state\n  snapshot to D1 and verifies an exact read-back. It does not remotely activate\n  prompts or change routing.\n\nAll experimental state stays under ignored `.voly/` paths. See\n[evaluation.md](docs/backend/evaluation.md),\n[capability.md](docs/backend/capability.md), and\n[production-validation.md](docs/backend/production-validation.md).\n\n## Web UI\n\nSvelte 5 SPA with hash routing: `#/tasks`, `#/gateway`, `#/telemetry`, `#/dspy` plus Cloudflare and Skill Marketplace drawers.\n\n| Component | Role |\n|---|---|\n| `RunPanel` / `RunParams` | Run a task (executor, agent, model, cwd), SSE stream, pre-run gates: skill suggestions + tech-stack confirmation |\n| `TechSelectionModal` / `CategoryPickerModal` | Pin framework versions before the run (runtime preflight badges); pick a project category when nothing is detected — greenfield cwd is scaffolded automatically |\n| `RunResult` | Result: content, billing chain, **Multi-agents** panel (role / tier / model / skills / cached) |\n| `PipelineInspector` | Pipeline stages, token flow, sub-agent assignments, memory, DSPy |\n| `GatewayPage` | Cache / rate / spend / fallback / DLP + by-provider / by-model / key health |\n| `TelemetryPage` | Spend analytics (daily, by_agent, by_model) |\n| `DSPyPage` | DSPy programs and lifecycle |\n| `CFPage` / `MarketplacePage` | Cloudflare workers + spend · skill catalog |\n\n## MCP server — VOLY inside any MCP host\n\n`voly mcp serve` exposes the orchestrator as nine MCP tools, so Cloudflare OS,\nClaude Desktop, or an IDE can start and follow runs without VOLY's own UI.\n\n```bash\npip install -e \".[mcp]\"\nvoly mcp serve --port 7799                  # → http://127.0.0.1:7799/mcp\n```\n\n| Tools | How a host treats them |\n|---|---|\n| `voly_list_runs` · `voly_get_run` · `voly_list_tasks` · `voly_get_task` · `voly_get_stats` · `voly_health` | Read-only — run immediately, recorded as observations |\n| `voly_start_run` · `voly_cancel_run` · `voly_submit_feedback` | Writes — queued for human approval |\n\n`voly_start_run` is annotated destructive and non-idempotent, so a host asks a\nhuman before it spends money and writes files — no deployment can auto-approve\nit. It returns a `task_id` immediately and the run continues in the background:\ncallers poll `voly_get_run`, then read the outcome with `voly_get_task`.\n\nProvider keys are not part of the deal. The host has its own model credentials,\nVOLY has its own, and neither side hands the other raw tokens — only tasks and\nresults cross the boundary. See [docs/backend/mcp.md](docs/backend/mcp.md).\n\n## DSPy — optional optimization layer\n\n| Mode | Behavior |\n|---|---|\n| `off` | DSPy disabled |\n| `shadow` | runs in parallel for observation; response stays classic |\n| `active` | DSPy result replaces classic for allowed agents |\n\n```bash\nvoly dspy status\nvoly dspy dataset build\nvoly dspy compile --agent reviewer\nvoly dspy promote code-review.v2 --tag production\n```\n\n## Configuration\n\n```yaml\n# voly.yaml (essentials — see docs/backend/config.md)\ndefault_cwd: \"\"              # target project path (or VOLY_PROJECT_CWD)\n\nai_gateway:\n  provider: cloudflare\n  cache_enabled: true\n  cache_persist_dir: .voly/gateway_cache\n  request_timeout_seconds: 15          # stall / legacy\n  request_total_timeout_seconds: 60    # full provider response budget\n  spend_limit_usd_per_day: 20.0\n  fallback:\n    enabled: true\n    chain:\n      - provider: deepseek\n        model: deepseek-chat\n\na2a:\n  enabled: true\n  auto_dispatch: true\n  min_flags_for_dispatch: 2\n  execution_mode: local\n  lead_mode: auto                      # skip premium lead chat on standard role sets\n  hybrid_code_gen: true                # developer/tester/devops → executors when cwd set\n  architect_max_tokens: 4096\n  task_timeout_seconds: 600\n\nplan:\n  enabled: true\n  mode: shadow                         # soft-verify; active = hard gates\n  command_timeout_seconds: 60\n  executor_require_git_diff: true\n\nauth:\n  enabled: false\n  cors_origins:\n    - \"http://localhost:7788\"\n    - \"http://localhost:5173\"\n\ncost_policy:\n  max_task_cost_usd: 1.0\n\ndspy:\n  enabled: false\n  mode: shadow\n```\n\nKey env vars:\n\n```env\nANTHROPIC_API_KEY=sk-ant-...              # claude-code / chat tier\nCURSOR_API_KEY=...                        # cursor executor (hybrid developer default)\nDEEPSEEK_API_KEY=...                      # deepseek executor + gateway fallback\nOPENCODE_API_KEY=...                      # zen / opencode\nCLOUDFLARE_ACCOUNT_ID=...\nCLOUDFLARE_API_TOKEN=...\nCF_AIG_TOKEN=...                          # CF AI Gateway\nVOLY_PROJECT_CWD=/path/to/proj            # default cwd for executor and UI\nVOLY_A2A_EXCLUDE_PROVIDERS=anthropic      # skip before first chat (credits)\nVOLY_A2A_EXECUTOR_DEVELOPER=cursor        # optional per-role override\nVOLY_AUTH_ENABLED=false\nVOLY_JWT_SECRET=\nVOLY_AUTH_USERS=admin:change-me\nOMNIROUTE_BASE_URL=http://localhost:20128\n```\n\n### BYOK — provider keys in Cloudflare (optional)\n\nWith `ai_gateway.byok_enabled: true`, keys for anthropic / openai /\ngoogle-ai-studio / deepseek are stored in **CF Secrets Store** and resolved by\nthe AI Gateway per request — no provider keys in `.env`, only `CF_AIG_TOKEN`.\nSee `docs/backend/ai-gateway.md` § BYOK (Store Keys).\n\n### Hosted catalog & marketplace (optional, opt-in)\n\nYou can use the official hosted skill catalog / marketplace instead of\ndeploying your own workers from `cf-workers/`:\n\n```env\nCF_WORKER_CATALOG_URL=https://catalog.voly.codes\nCF_WORKER_MARKETPLACE_URL=https://marketplace.voly.codes\n```\n\n`voly setup` offers to write these for you. Privacy note: catalog/skill\nqueries then go to those workers; nothing is sent unless you opt in.\n\n## Core commands\n\n```bash\nvoly run <task>                        # pipeline (→ multi-agent when complex)\nvoly run <task> --executor claude-code --cwd /path/to/project\nvoly match <task>                      # pick agent / executor / model\nvoly status                            # component health\nvoly savings                           # savings report\nvoly ui                                # web dashboard (FastAPI + Svelte) :7788\nvoly serve                             # pipeline HTTP runner :9202\nvoly mcp serve                         # VOLY as an MCP server for MCP hosts :7799\n\nvoly registry agents | skills          # agent / skill registry\nvoly model list                        # models and pricing\nvoly ai-gateway status                 # AI Gateway status\nvoly spend status                      # current daily spend\nvoly dspy status                       # DSPy programs + mode\nvoly plan list | show <id>             # multi-agent plans + verify status\nvoly eval validate <dataset.json>       # validate an offline golden dataset\nvoly eval run <dataset.json>            # deterministic regression replay\nvoly eval calibrate                     # compare LLM-judge decisions with human feedback\nvoly research shadow \"<task>\" --cwd .   # evidence-first reuse/adapt/build recommendation\nvoly memory compact handoff.json        # import typed strategic memory\nvoly memory context \"<query>\" --cwd .   # preview bounded memory retrieval\nvoly learning shadow \"<task>\"           # preview relevant approved instincts\nvoly hooks dispatch <event> <run-id>    # run approved constrained lifecycle hooks\nvoly capability import ecc --source /path/to/ECC --dry-run\nvoly capability pack list               # inspect staged, checksummed capability packs\nvoly capability evaluated benchmark     # offline routing probe; never activates a pack\nvoly cloud login --url https://cloud.voly.codes   # browser confirm; shared run history\nvoly cloud sync                                 # upload past local runs after link\nvoly reuse search \"<task>\"             # GitHub code reuse (also: pack | pick | apply)\nvoly reuse run \"<task>\" --cwd /path/to/project  # full reuse pipeline (dry-run apply)\n```\n\nMore groups (`voly --help`): `a2a`, `agui`, `capability`, `eval`, `evidence`,\n`research`, `memory`, `learning`, `hooks`, `workflow`, `rtk`, `headroom`,\n`pxpipe`, `mcp`, `runner`, `telemetry`, `runs`, `catalog`, `skill`, `scan`,\n`compare`, `balance`, `tunnel`, `init`, `setup`, `config`.\n\n## CI and tests\n\n```bash\npytest tests/test_dspy_runtime_smoke.py     # required after changes\npytest tests/test_multiagent_smoke.py       # multi-agent (mock gateway)\npytest tests/test_web_auth.py               # JWT auth baseline\npytest tests/ -q                            # full suite\n```\n\nThe package requires Python 3.10+. CI runs the base suite on the current Python\nrunner, the DSPy suite on Python 3.11, and clean-wheel installation checks on\nWindows, macOS, and Linux with Python 3.13.\n\n## Do not commit\n\n```\n.voly/events/  .voly/dspy/  .voly/reports/  .voly/eval-runs/  .voly/gateway_cache/\n.voly/capability/  .voly/research/  .voly/learning/  .voly/hooks/\n.venv/  ui/node_modules/  voly/web/static/\n```\n\n## Documentation\n\n| File | Purpose |\n|---|---|\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | High-level map: pipeline, executor, gateway, A2A |\n| [docs/backend/pipeline.md](docs/backend/pipeline.md) | Stages, AgentRouter, hybrid multi-agent, cascade |\n| [docs/backend/a2a.md](docs/backend/a2a.md) | A2A modules, auto-dispatch, federation, context handoff |\n| [docs/backend/plan.md](docs/backend/plan.md) | Plan gates, verify, scoped pytest |\n| [docs/backend/executors.md](docs/backend/executors.md) | Executors, billing fallback chain, WranglerExecutor |\n| [docs/backend/ai-gateway.md](docs/backend/ai-gateway.md) | AIGateway, providers, OmniRoute, persistent cache |\n| [docs/backend/reuse.md](docs/backend/reuse.md) | Code reuse: GitHub search → pack → pick → apply, auto mode |\n| [docs/backend/evaluation.md](docs/backend/evaluation.md) | Eval policies, golden replay, LLM judge calibration, human review |\n| [docs/backend/capability.md](docs/backend/capability.md) | Capability registry, discovery, quarantine, staged packs, Cloudflare sync |\n| [docs/backend/evaluated-capability-packs.md](docs/backend/evaluated-capability-packs.md) | Evidence-gated agent/skill routing and retirement |\n| [docs/backend/production-validation.md](docs/backend/production-validation.md) | Paired pilots, held-out validation, quality/token/latency gates |\n| [docs/backend/research.md](docs/backend/research.md) | Research-first shadow recommendations |\n| [docs/backend/strategic-memory.md](docs/backend/strategic-memory.md) | Typed, scoped, budgeted memory compaction |\n| [docs/backend/continuous-learning.md](docs/backend/continuous-learning.md) | Evidence-gated instincts and skill candidates |\n| [docs/backend/lifecycle-hooks.md](docs/backend/lifecycle-hooks.md) | Allowlisted lifecycle events, permissions, and audit logs |\n| [docs/backend/dspy.md](docs/backend/dspy.md) | DSPy programs, TaskPlanner, adapter, datasets |\n| [docs/backend/config.md](docs/backend/config.md) | voly.yaml, env vars, VOLYConfig |\n| [docs/backend/api.md](docs/backend/api.md) | FastAPI endpoints, SSE, JWT auth, CF Worker /infer |\n| [docs/backend/mcp.md](docs/backend/mcp.md) | MCP facade: the nine tools, annotations, connecting a host |\n| [docs/backend/sdk.md](docs/backend/sdk.md) | Public `Agent`/`Workflow` SDK facade over AIGateway/AgentRunner/Plan |\n| [docs/frontend/overview.md](docs/frontend/overview.md) | Svelte 5 stack, ui/ layout, dev/build |\n| [docs/frontend/components.md](docs/frontend/components.md) | UI components, props, pre-run gates |\n| [docs/frontend/api-client.md](docs/frontend/api-client.md) | UI API calls, SSE events, fallback handling |\n| [CLAUDE.md](CLAUDE.md) | Instructions for AI agents in this repo |\n| [README_ru.md](README_ru.md) | Russian version of this README |\n\n## Contributing & License\n\nContributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) (DCO, rules, open-core boundaries). Licensed under [Apache 2.0](LICENSE).\n",
  "bytes": 29300,
  "sha": "cd5faa521cb299e87a6e756f442dc47ee97ff27d853f238c7e6d336fad439ad9",
  "repo_slug": "voly-codes/voly",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_voly_codes_voly_openwiki_index_md_e56cf851/readme"
}