Just ask, then confirm.

oah is for developers and small teams who already use git and pull requests and want production-grade review discipline on their own machine. It was made first of all for people dissatisfied with AI coding results or setting up their first harness.

The current release, v0.3.0, still expects you to be fluent with git and pull requests: you work on branches, push, open a pull request and confirm the landing yourself.

macOS 13 or newer and Windows 11, natively, without WSL. Windows 10 22H2 works on a best-effort basis. Linux is not yet supported.

oah runs on Python 3.11+ with the standard library only. The CI starter can still test your own project on Linux runners (ubuntu-latest) if you choose them; that is separate from where oah itself runs.

oah itself is MIT-licensed and needs no key. You install and sign in to the engines yourself: Claude Code needs a Pro, Max, Team, Enterprise or Console account, and Codex accepts a ChatGPT plan or an API key.

Optional extras have their own terms: TypeSafe Jev needs your own TypeSafe account and key, and TypeSafe may charge for each request. Aside has a free plan. Required-check rulesets on private GitHub repositories need GitHub Pro, Team or Enterprise Cloud. The docs do not state prices.

Run the installer once, then run oah init once in each project (a git repository with a remote), and commit the files it writes. From then on, open your AI in that project and talk to it in plain words, for example “Build login with oah.”

The worked example, examples/hello-oah, walks one small task through the whole loop and takes about 20 minutes. It shows what you say, what the AI does and what you check, followed by the complete command walkthrough.

The oah command drives Claude Code and Codex CLI today. The ideas — leases, engine stages, evidence gates, the impact map, the wiki and the review loop — work with one AI or several, including other tools and harnesses. Take the parts you need and give each stage to the AI that suits you.

Inside oah, [stages] in .oah/config.toml sets which engine does each stage. A call for the wrong engine is refused unless you pass --override-stage, which is recorded. When one engine both writes and reviews, the review receipt honestly says the review was not independent.

This split comes from the author's own experience, not a measured comparison. In the author's use, Claude is good at filling in details a beginner might miss while building the first version, and Codex is good at checking and correcting work within a fixed scope.

So Claude writes first; Codex reviews, corrects and reviews again. You can change the stage assignment in .oah/config.toml if a different split suits you.

No. Jev is the recommended, optional judge. Without a key, or with it turned off, the fixed rules decide, and results say rerank=unused(no key) or rerank=unused(not-enabled). A key alone never turns it on: you also enable it, and oah init asks once.

In v0.3.0, Jev re-orders chosen skills and judges difficulty from the Intent and Scope paths. Its tier runs only at sufficient confidence, never below the risk floor. When Jev is off, fails or is unsure, the rules decide. A Jev failure never blocks a call.

A gate proves that its CHECK command produced the EXPECT output, run through unlazy after you approved the command, with the evidence recorded and bound to its inputs. A later change to an input makes the gate run again, and oah finish refuses unmet gates.

It does not prove more than its command checks. Gate inputs are tracked files, untracked files that are not ignored, and the run environment, so a change to an external service or an ignored untracked file does not make a gate rerun; check those separately. oah review summary and oah gates status read gate boxes structurally and re-run nothing, so a ticked box can still be stale.

A lease reserves the paths one task may change. A second lease whose scope overlaps is refused with OAH_LEASE_CONFLICT, which names the holder, so two AI sessions do not start on the same files by accident. With the opt-in pre-push hook, a push is also refused while a lease is recorded for the worktree.

A lease cannot stop an editor from writing elsewhere. Instead, oah finish compares the files really changed since the lease started with the scope and refuses with OAH_SCOPE_EXCEEDED. Leases last 4 hours by default and show as STALE after that.

Rounds continue while each brings new findings in scope. P0 and P1 findings block and are corrected by oah fix; a round that approves, or reports only P2 and P3 findings, ends the series, and the follow-ups are recorded.

The loop asks you only when it must. It stops with OAH_REVIEW_NEEDS_DECISION when a finding repeats a kind an earlier correction already tried to fix, or when the fix needs a design or stored-format change. You decide, then continue with oah review --task <task> --decision "<what you decided>", which is recorded.

There is no fixed number of rounds. If you want a limit, set [review] max_rounds. Reaching it stops with OAH_REVIEW_ROUNDS_EXHAUSTED; --extra-round continues and is recorded, or you can raise or remove the limit.

Separately, if several reviewer calls in one round fail without counting, oah stops calling the paid reviewer with OAH_REVIEW_ATTEMPTS_EXHAUSTED. Read the last run's stderr.log, fix the cause, then rerun with --extra-attempt.

The shared rules block tells agents not to push or force-push, and landing is a command you confirm. oah land --check checks the lease, intent, review, gates, impact, required checks, fast-forward, a gitleaks scan and CI at the exact head.

oah land --merge runs every check again, asks you to confirm by typing y, and only then fast-forwards the remote default branch to exactly the reviewed head, provided it still equals the commit just checked. Unverified CI blocks by default unless you record an explicit, per-head exception; failed or pending CI always blocks.

The installer never sees your passwords or keys; installers that need a password ask for it themselves. Claude Code and Codex keep their own credentials, and oah only runs their status commands (claude auth status, codex login status) to read whether you are signed in. Companion-app setup reads only the sign-in status column and discards command output.

Optional keys are read only at runtime, from an environment variable or the OS keychain. oah never asks you to paste a key into a file and never writes one, prints one, or puts one in a brief, a run record or an error message.

The engines you sign in to, Claude Code and Codex, do the implementation and review work. Skill-selection records stay in a local file in the state folder and are never sent anywhere.

With Jev enabled, requests go to TypeSafe. In v0.3.0, difficulty judging sends the task's Intent text and Scope paths, up to 16,000 characters, never code, diffs, file contents or your key, and a privacy check sends nothing when it flags a part. In v0.3.0, a model-catalog rebuild downloads Epoch AI's public benchmark file; that request sends nothing about your project, tasks or you, and [models] fetch_scores = false stops it.

Nothing until you confirm. oah init first asks once about each option, checks your tools and sign-ins, and shows the complete plan. After you confirm, it writes .oah/config.toml, the rules block in AGENTS.md (imported by CLAUDE.md), the wiki in docs/wiki/, templates in .oah/templates/ and .gitignore entries for local secret files, then builds the first impact map. Commit what it wrote.

A second run writes only what is still missing. It never replaces your files without --force, and never the wiki's index or log. Companion-app steps marked [global] change files in your user folder, and each asks first.

Finish or release open leases first. From a clone, run git pull and then the installer again with --skip-tools (-SkipTools on Windows). From a release, download the new tag's source archive and SHA256SUMS, and extract it only after the digests match. Then check oah --version and oah doctor in a new terminal.

In each project, oah rules check and oah rules sync refresh the managed rules block, oah init writes only what is missing, and oah models --refresh rereads the model lists. Skills, unlazy and MCP template pins each have their own update path on the Upgrade page.

The pinned docs do not describe uninstalling oah itself. They do describe removing the companion apps (for example claude mcp remove aside --scope user, codex mcp remove aside, and uninstalling the apps), and oah hooks removes the opt-in hooks.

Documented recovery steps include oah wiki recover after an interrupted log rollover, moving an incompatible unlazy copy aside and rerunning oah init --with-unlazy, oah release --reason to drop a lease without finishing, and, for a leaked key, rotating it at the provider first before cleaning the history.

Every refusal starts with an OAH_* code and the rest of the message says what to run next, naming the file, lease or gate involved. Exit code 1 means refused (fix what the message says and rerun), 2 usage or a preflight ABORT, 69 environment, and 75 that oah wait timed out with the run still active.

Run oah doctor first, then search the Troubleshooting page for the code; it groups common codes by step with what each means and what to do next. oah status, oah intent show <task> and oah gates status <task> help when you are still stuck.

Landing reads CI results for the exact head through gh. Missing gh, no results (including when you installed no workflow) or a missing required check makes CI unverified, which blocks landing by default. You can record an explicit per-head exception with --accept-unverified-ci "<reason>", and CI then stays unverified, never a pass.

oah ci init writes a starter workflow after showing it and asking: your tests on the operating systems you choose plus a pinned gitleaks scan, with read-only permissions and actions pinned to full commit SHAs. oah never changes repository settings; making checks required is a GitHub ruleset you add yourself.

No. Both are optional, and nothing in oah needs them; oah doctor lists them as optional, and a missing optional app never makes it fail. Setup offers each one with a line on what it adds and installs only what you confirm; --yes never installs them.

Orca runs coding agents side by side, each in its own git worktree, and oah call --launcher orca can run a worker in an Orca terminal. Aside is a browser with an AI agent that Claude Code and Codex use for web tasks through MCP; it does not run on Linux.

oah is released under the MIT License, copyright open-agent-harness contributors. Bundled skills under skills/ ship unchanged where their licenses allow it, with their own licenses and provenance records.

THIRD_PARTY_NOTICES.md credits the adapted diagram-design templates (MIT), Tabler Icons (MIT), Epoch AI's benchmark data (CC BY 4.0), and the tools oah runs or links to, including unlazy, superpowers, graphify, Claude Code and Codex CLI.

Update oah, then run oah rules sync in each project. oah --version should print oah 0.3.0. The new rules ask your AI to judge design difficulty first; without them, packet creation warns OAH_DESIGN_UNJUDGED. Your configuration is not edited.

Model choice now follows scores unless you pin a model. Existing projects keep tool updates off. With Jev enabled, the first expanded Intent-and-Scope request prints OAH_RERANK_SCOPE_WIDENED. Read the upgrade guide for model floors, pins and the options to turn off score downloads or Jev.

v0.3.0 is the current published release: models chosen from benchmarks. Benchmark scores pick the model, with performance, balanced and efficient profiles; scores come from Epoch AI with no key, or from your own Artificial Analysis key; new model generations join and drop out automatically with notices; Jev judges difficulty from the Intent and Scope paths with a rule-based fallback that never blocks; reviews never run below their risk floor; opt-in tool updates run after the last lease; and oah models report and export count how choices were made. Your pins, tier pools, effort caps and task floors stay in force.

Published on November 4, 2026. The release includes pinned installers, source archives and SHA256SUMS. The guided design conversation remains planned for v0.4.0.

A guided design conversation: you say what you want to build, and oah asks one design question at a time with a recommendation, so you take part in the design decisions before implementation begins. It is planned, not available yet.

Today you can already discuss the goal with your AI and answer decisions when the review loop stops.