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.
Run oah init once in each project, a git repository with a remote. It asks once about each option, checks your tools and your Claude Code and Codex sign-ins, shows the complete plan, and changes files only after you confirm. Then it writes the config, rules block, wiki and templates and builds the first impact map.
When you need it
Setting up a harness by hand means many files, tools and sign-ins to get right, and a setup that silently changes your project is hard to trust.
How it works
Inside your project, run oah init.
It asks once about each option: tier agents, hooks, unlazy (the gate checker), the knowledge graph, the CI starter, the companion apps Orca and Aside, the TypeSafe Jev re-ranker and automatic skill updates.
It checks every tool and installs only what you confirm, and checks your Claude Code and Codex sign-ins with their own status commands, showing the command to run when one is missing.
After you confirm the complete plan, 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.
The last line is OAH_INIT_DONE, or OAH_INIT_INCOMPLETE with what is still to do. Commit what it wrote; from then on the installed rules tell your AI how to run the harness.
Example
Run once per project, in a git repository with a remote.
oah init
Requirements
oah installed, and a git repository with a remote.
Each question also has a flag, such as --with-unlazy or --without-ci, so you can answer without a prompt.
Limits and recovery
A second run writes only what is still missing; it never replaces your files without --force, and never the wiki's index or log.
Init does not add Python bytecode patterns to .gitignore; the worked example appends __pycache__/ and *.py[cod] before running gates.
For unlazy repairs, avoid --force: it does not replace an incompatible project copy and can reset .oah/config.toml to defaults.
In v0.3.0, init also asks once about tool updates after a finish.