omh documentation
oh-my-zsh for agentic coding — the best agentic coding environment without the hassle of understanding, installing, and configuring everything.
Status: early. 0.14.1. This release is about memory another session can
use, and a sandbox whose git can merge. One note store per repo at
~/.omh/memory/<repo>, shared the moment a note is written and never
committed — omh memory — and a base image on
Debian 13, because Debian 12’s git 2.39.5 failed any check that merges.
0.13.0 ran the harnesses their makers ship now: every pin moved to its current
release and each adapter was re-read against it; the two claims that broke were
fixed rather than carried. omh auth codex
finishes — a device code, or --import of the login this machine has — Codex
runs omh’s hooks, omh sNN reads its rollouts, and an
account can name one
harness’s login with codex:work. An unreadable worktrees/ no longer reads as
no sessions. omh sNN rm
that can tell a squash already landed a branch, and harness names that cannot
be paths, arrived in 0.12.0,
which hooks fired and the opt-in
guards in 0.11.0,
omh upgrade and the checks omh sNN commit runs
before landing in 0.10.0, the silent failures
closed in 0.8.0, the command surface landed in 0.7.0 and
the work loop in 0.6.0.
0.14.1 is repairs: no editor could attach to a session, a fresh install’s
omh doctor ended red on a memory server it
had never built, and several session lifecycle paths could lose work or leave a
worktree unusable. 0.14.0 retired the committed note layer and omh memory promote with it, and
moves the store to ~/.omh/memory/<repo> — a store under the old path moves
itself, once, and says so. omh doctor gained a git row that asks the image
rather than the host. 0.13.2 let Codex run commands and edit files: its own
sandbox cannot start inside omh’s container, so omh turns it off. 0.13.1 fixed
two launches 0.13.0 broke: opencode died on start over a
directory the image left to root, and Codex could not save its own config.
omh doctor asks first whether a harness
starts at all.
One harness (claude) has been driven for real work; opencode, omp and
codex pass omh doctor, which proves their paths and nothing about their
behaviour. Docker is the only end-to-end-verified runtime; podman and sbx
are opt-in. Several design pages describe work that is partly
built — each says which parts, at the top. See the roadmap.
Start here
Section titled “Start here”If you have five minutes and a repo, install omh and follow Your first session. It goes from nothing to a sandboxed agent with your setup already inside it.
Using omh
Section titled “Using omh”| Installation | Homebrew, the install script, or from source |
| Your first session | omh init, logging in, and running an agent |
| Commands | every command, what it does, what it prints |
| Configuration | the catalogue, settings and their layers, provenance, carry_in |
| Sessions | what a session actually is, the git the agent gets, persistence, worktrees |
| Accounts | omh auth, several logins per harness |
| Editors | attaching VS Code, Zed, Cursor or Neovim over SSH |
| Code graph | the graph, the four hooks, omh graph |
| Troubleshooting | omh doctor, and the failures it exists to catch |
Understanding omh
Section titled “Understanding omh”These explain why, and are worth reading before proposing an architectural change — most of them record something that was tried and cost something. They are design pages, kept beside the source and read on GitHub.
| Why a distribution | the thesis, why not an app store, who else is in this space |
| Decisions | every load-bearing choice with its reasoning |
| The base set | omh’s opinion as a versioned data file, and the test that makes an entry earn its place |
| Architecture | images, runtime backends, on-disk layout |
| The profile | built — one catalogue, [use] per repo, rules composed with the repo’s own, omh’s hooks and sections generated from the base set, and the command surface 0.7.0 settled on top of it |
| Adapters | harnesses and editors as data, and how to add one |
| Adoption | partly built — what init decides when it meets a repo, the toolchain probe, and what omh import still has to migrate |
| Git | built in 0.6.0 — the loop around the sandbox’s repository: reading a session’s work, landing it in stages, staying current with trunk, and reaching several sessions from one place. Twelve steps, each naming the pull request that landed it |
| Memory | the note graph, its guards, and the build order — the store, retrieval and staleness are built; hub pages are not, and the committed layer the spec describes was removed in 0.14 |
| Memory: how the design got here | the survey, the benchmark that reversed six choices, and the alternatives not taken |
| Memory M0: running iwe | the blocking spike, and the four claims the design rested on that did not survive it |
| Measuring retrieval | the benchmark that decides retrieval questions, and why it cannot be tilted |
| Trust | provenance, evidence, and a credible exit |
| Risks | what is weak, stated plainly |
| Roadmap | what ships when, and what gates what |
Contributing
Section titled “Contributing”Contributing — the testing rules, the invariants that must keep holding, and the one thing about this codebase that will mislead you if nobody tells you first.
A note on how these pages are written
Section titled “A note on how these pages are written”Claims here are meant to be checkable. Where a number appears it was measured on this repo and says so; where something is unverified it is marked unverified.
That is not modesty. Almost every bug this project has shipped lived at the
boundary between omh and external software, where a confident sentence in a
document and a green test suite are equally worthless — see
Troubleshooting for why omh doctor exists and what it
can prove that nothing else can.