code-oz

code-oz

CI-style gates for AI coding agents.

code-oz runs coding agents through a repo-local delivery loop:

DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP

Use it when direct AI coding is too unconstrained and you want every change to pass through inspectable artifacts, approval gates, verification evidence, and independent review before it ships.

AI agents are fast. code-oz makes their work auditable. It is for risky repos, not fastest-loop coding.

macOS note: code-oz binaries are not yet Apple-Developer-signed (signing + notarization deferred to v0.x stable). Gatekeeper may prompt on first launch; the install script applies xattr -d com.apple.quarantine as a workaround, and brew install handles this automatically.

What you get

• file-based phase gates you can inspect in the repo
• approvals bound to exact artifact SHA-256s
• isolated worktrees for agent changes
• an events.jsonl ledger for reconstructing what happened
• cross-family review so the builder and reviewer are not the same model family

Status: public alpha. The deterministic demo uses FakeProvider so you can inspect the lifecycle without spending tokens. FakeProvider proves lifecycle gates and ledger determinism, not model quality.

Install

Three channels deliver the same single binary, verified against the same checksums.txt.

# curl | sh
curl -fsSL https://github.com/omerakben/code-oz/releases/download/v0.21.1-alpha.0/install.sh \
  | sh -s -- --version v0.21.1-alpha.0

# npm (scoped under the TUEL AI publisher; binary still runs as `code-oz`)
npm install -g @tuel/code-oz

# Homebrew
brew tap omerakben/code-oz
brew install omerakben/code-oz/code-oz

Platform support: macOS arm64, macOS x64, Linux x64, Linux arm64. Windows and Scoop are deferred to a future distribution milestone.

If npm install -g @tuel/code-oz fails with a 404 or authentication error, your ~/.npmrc is likely overriding the @tuel scope — see docs/TRUST.md § Install gotchas for the fix.

Use it inside Claude Code (plugin)

code-oz ships two Claude Code plugins through a marketplace declared at this repo's root. From a Claude Code session, add the marketplace and install:

/plugin marketplace add omerakben/code-oz
/plugin install code-oz@code-oz-marketplace

The code-oz plugin is a thin wrapper. It adds /code-oz-run, /code-oz-init, /code-oz-doctor, and /code-oz-resume, and each command discovers the code-oz engine on your PATH, falling back to npx @tuel/code-oz when the binary is absent. Install the engine from the channels above for the fastest path. The plugin never writes gates, events, or reviews — the engine binary is the only writer, so the gate guarantees hold whether you drive code-oz from the CLI or through the plugin.

A second plugin, code-oz-discipline, is optional. It installs advisory-only skills (brainstorming, source-check, RED-first) that are guidance, not enforcement:

/plugin install code-oz-discipline@code-oz-marketplace

Adding the marketplace clones this repository into Claude Code's plugin cache. The repo is the full engine source, so from the CLI you can restrict the checkout to just the plugin files:

claude plugin marketplace add omerakben/code-oz --sparse .claude-plugin plugins

Why not just Claude Code or Codex?

Use Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Roo Code, or Aider directly when you want the fastest possible agent loop.

Use code-oz when you want a governed loop.

Direct-agent workflow:

1. Ask an agent to make a change.
2. Inspect the result.
3. Hope the prompt, tests, and review were enough.

code-oz workflow:

1. Define the task as an artifact.
2. Approve the artifact by SHA-256.
3. Build in an isolated worktree.
4. Verify evidence before review.
5. Require independent review.
6. Write a ledger of what happened.

code-oz is not trying to be a smarter coding model. It is the control layer around coding models.

What is real today?