oah helps you build an AI development workflow that fits you and keeps changing as AI improves. It is a working reference and a guide you can adapt.
A useful result needs more than generated code: the scope must be clear, the changes checked, and decisions kept for the next session. oah connects those steps so one request can carry through the work with a record of what happened.
002 / Why it keeps changing
Older rules and skills can hold a newer model back or make its results worse. Defaults should be easy to understand and change; a rule that gets in your way is a design problem to fix.
Keep the parts that help, remove what no longer helps, and revise the workflow as your tools improve. You can start with the full setup or take only the impact map, wiki, leases, evidence gates or review loop that your project needs.
003 / Why Claude builds and Codex reviews
This split comes from the author's own experience, not a measured comparison: Claude fills in details a beginner might miss in a first version; Codex checks and corrects within a fixed scope.
The current commands run Claude Code and Codex CLI. The ideas can also be adapted to another tool or harness, with one AI or several. Give each stage to the AI that suits your work.
004 / From one request to a checked change
Describe the result you want in plain language. The AI records the goal and scope, checks what the change touches, reserves its paths and chooses the tools for the task. Claude builds; Codex reviews, corrects and reviews again.
Gates record the checks and their results. The project wiki keeps the decisions and reasons beside the code. In v0.3.0, optional TypeSafe Jev can judge difficulty for model selection; rules remain the fallback when it is unavailable or uncertain.
005 / The decisions stay with you
You ask, answer when the AI needs a decision, and confirm before the change lands. If the same problem repeats or the work reaches a design choice, the loop stops to ask you.
Ask “Is the review done?” or “Did all the gates pass?” and inspect the evidence. The final confirmation belongs to you; writing code, checking it and approving its landing are separate steps.
006 / Free, open source, yours to adapt
oah is free, open-source software under the MIT license. Read the source, change it and bring the useful pieces into your own workflow. Your AI services and any optional services use their own accounts and billing.
The current v0.3.0 release supports macOS and native Windows, and expects familiarity with git and pull requests. Install it, run oah init in your project, then try the small hello-oah example. The installation and documentation sections explain each step.
Scores from Epoch AI, or your own Artificial Analysis key
New in v0.3.0: scores come from Epoch AI, with no key and no account. With your own Artificial Analysis key, oah uses those scores instead. Each release ships an Epoch AI snapshot, a catalog rebuild refreshes it over HTTPS, and the request sends nothing about your project, your tasks or you.
When you need it
Model choice by score is only as good as its data, and fetching that data must not leak anything about your work.
How it works
At a catalog rebuild — after a CLI update, after [models] ttl_hours (24 by default), or with oah models --refresh — oah fetches https://epoch.ai/data/benchmarks.csv when its stored copy is older, missing or damaged, with a 10 second timeout and a size limit.
With ARTIFICIAL_ANALYSIS_API_KEY stored, oah also asks Artificial Analysis, sending the key only in the x-api-key header, and keeps one index per matched model.
Each engine uses one source per launch: Artificial Analysis when its copy scores the newest listed model of every known family, else the latest Epoch AI fetch, else the shipped snapshot. Sources never mix.
Copies stay in oah's state folder (models/benchmarks-epoch.json, benchmarks-aa.json); a damaged or changed file counts as absent (OAH_SCORES_FILE_INVALID).
[models] fetch_scores = false stops every fetch, and the shipped snapshot chooses.
Example
Store your own Artificial Analysis key in the macOS keychain (from Keys).
security add-generic-password -s oah -a ARTIFICIAL_ANALYSIS_API_KEY -w
Requirements
Requires v0.3.0 or later.
No key for Epoch AI. Optional: your own ARTIFICIAL_ANALYSIS_API_KEY in the environment or the OS keychain.
Limits and recovery
Unlike the Jev re-ranker, the Artificial Analysis key alone turns this on, because [models] fetch_scores is true by default.
Matching Artificial Analysis rows by name follows its documentation and is not yet confirmed against a live response.
A failed fetch keeps the last good copy and says so once (OAH_SCORES_REFRESH_FAILED); a launch never fails because of it.
Remove the key and oah stops using the data and deletes its copy at the next refresh.