VNX Orchestration

<div align="center">

# VNX Orchestration

### Governance-first runtime for AI coding agents

**Glass-box governance · Multiple CLIs on subscription, not per-call API credit · Local NDJSON receipts**

[![PyPI version](https://img.shields.io/pypi/v/vnx-orchestration?color=1f6feb&label=pypi)](https://pypi.org/project/vnx-orchestration/)
&nbsp;![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
&nbsp;[![License: MIT](https://img.shields.io/github/license/Vinix24/vnx-orchestration?color=2ea043)](LICENSE)
&nbsp;[![CI](https://img.shields.io/github/actions/workflow/status/Vinix24/vnx-orchestration/public-ci.yml?branch=main&label=CI)](https://github.com/Vinix24/vnx-orchestration/actions)

[![Stars](https://img.shields.io/github/stars/Vinix24/vnx-orchestration?logo=github)](https://github.com/Vinix24/vnx-orchestration/stargazers)
&nbsp;![Forks](https://img.shields.io/github/forks/Vinix24/vnx-orchestration?logo=github)
&nbsp;![Vendor SDK](https://img.shields.io/badge/vendor%20SDK-none-24292f)

**[Docs](docs/) · [Architecture](docs/core/00_VNX_ARCHITECTURE.md) · [State Fabric](docs/core/STATE_FABRIC.md) · [ADRs](docs/governance/decisions/) · [Writing](https://vincentvandeth.nl) · [Changelog](CHANGELOG.md)**

</div>

---

VNX runs AI coding CLI workers in isolated git worktrees, through review gates, with an append-only NDJSON receipt per dispatch.

It is a local control plane for the AI coding CLIs that already sit on your machine. One orchestrator dispatches work to ephemeral workers; each worker runs in its own git worktree; review gates decide what merges; every dispatch leaves a receipt. VNX drives `claude`, `codex`, `gemini`, `kimi`, and local `ollama` with no vendor SDK. It calls the CLIs as subprocesses and never imports a provider library.

That has two distinct payoffs. First, governance: every dispatch is reconstructable, from what was assigned to what was reviewed to what merged and what each gate cost. Second, billing: because the workers are the CLIs themselves, the claude, codex and kimi lanes bill the subscriptions already on the machine, not per-call API credit. That is measured, not assumed: `cost=$0.0000` receipts under a `subscriptionType: max` auth state (see "Billing follows auth, not the lane"). It does not hold for every lane. GLM, DeepSeek and any OpenRouter-routed model bill API credit, and only run where a project chose them or as a fallback when the subscription reviewers are unavailable (see "Multi-provider architecture" below).

Most agent projects build SDK-native agents. I orchestrate the binaries instead.

I built this for my own work, an estimated 3,000+ hours of development since February 2025. It is open source because the architecture is portable. Source is at [github.com/Vinix24/vnx-orchestration](https://github.com/Vinix24/vnx-orchestration).

This is not a security sandbox; it isolates work with git worktrees. It is not compliance certification; it produces a local, append-only, inspectable audit trail. It is optimized for human-gated coding workflows, not fully autonomous merges.

## What's new in 1.6

Seven releases on the 1.6 line so far (1.6.0 through 1.6.6, August 20 to September 27, 2026), all documented in the [CHANGELOG](CHANGELOG.md). The headlines:

- **The review stack picks a subscription reader first** (1.6.6, #1928): the default is `codex_gate,kimi_gate`; `glm_gate` (OpenRouter credit) and `deepseek_gate` (own key) run only as a takeover-chain fallback when both subscription reviewers are unavailable.
- **Gemini is retired as a reviewer** (1.6.6, #1932, #1934, #1935, #1936): the name is refused everywhere a review gate is selected, in defaults, profiles, enforcement YAML, the dashboard toggle and the docs. An existing `gemini_review` result in history still reads as a verdict, and the gemini CLI stays in use as a worker lane, just not as a reviewer.
- **A partial read no longer books a pass** (1.6.6, OI-1851, #1920, #1937): a PASS on a diff a harness-lane gate could not fully read is `partial_review`, not a pass, and the merge door refuses it. Each harness-lane gate also got its own diff-char cap instead of one shared constant (kimi 400,000; glm and deepseek 50,000).
- **T0 context rotation is enforced, not just recommended** (1.6.6, #1923): crossing 500K tokens in a T0 session now blocks new work until rotation runs.
- **Build workers default to sonnet, T0 is pinned to Opus 5.5** (1.6.3, #1890): a claude-lane build-worker dispatch with no explicit model resolves to sonnet; before it resolved to kimi-k3 and was rejected. The pin is a default a dispatch spec can override, not a hard lock.
- **Branch protection strictness is set per project** (1.6.5, OI-1849, #1917): `enforce`, `warn` or `off` in `branch_protection.yaml`, with the CI check as the floor under every setting, and the merge door judges the repo it is merging into rather than the repo it is installed from.
- **The interactive tmux dispatch lane was retired** (1.6.2, #1845; r

... (truncated)