Skip to content
omh

Your first session

From a repository to a sandboxed agent that already has your rules, skills and MCP servers, once omh is installed. Roughly five minutes, most of it the first image build.

Set up a repo

Section titled “Set up a repo”
Terminal window
$ cd ~/code/your-project
$ omh init
omh init — decided, asked nothing


  harness    claude  (found on your host)
  image      omh/claude:b4edd8fd15d4d669 (already built)
  image      omh/claude:8eae0d5c1511fa89 (this repo's toolchain)
  stack      rust (from Cargo.toml)
  hooks      2 selected  (4 more in your catalogue)
  provision  rust/linker
  provision  rust/toolchain
  memory     2 notes written, 0 already there
  graph      indexing in background → omh-cache-your-project-a8c4d1cd


  catalogue  /Users/you/.omh
  this repo  /Users/you/code/your-project/.omh  (committed)


  base set (2026.08)
    codegraph  structural queries instead of re-grepping the repo every task
    memory     what a session learned outlives it — a removed session leaves no transcript to grep


  omh why <name>  what it costs, what was considered instead, how to remove it


  next
    omh new claude  start a session
    omh s           list sessions, each by its id
    omh sNN resume  rejoin one later
    omh sNN attach  open it in your editor

The base set is a versioned file, not something buried in the binary — init seeds from it and omh why explains from it, which is why they cannot disagree about what you just got.

init decides and reports — it never asks. Every question is hassle omh promised to remove, so the bar for asking one is high enough that nothing has cleared it yet: see derive, never interrogate.

What it actually did

Section titled “What it actually did”
1  repo check                     fail fast, before any work
2  ensure ~/.omh: the catalogue, bundled adapters, editors, the base set
3  detect the stack; read the host for a harness *preference*
4  write ~/.omh/mcp.json and <repo>/.omh: settings, [use], memory, a hook per stack
5  seed memory by derivation       README, manifests, git log, existing rules
6  ensure the image                ← the real blocker; nothing runs without it
7  index the code graph            background, resumable

The report is the final step. Every decision above is collected and printed once, which is why the image and graph lines — made at 6 and 7 — are in it, and why --json can be one object rather than six unrelated ones.

[use] is written expanded, with every catalogue entry named, because a list you curate by deleting lines beats a wildcard you cannot review. Anything you add to your catalogue afterwards is not in it, so the launcher names what is not selected — see Configuration.

Step 4 never overwrites what you already wrote, and writes no rules file at all: omh’s own sections are base-set entries, composed into every session from the manifest. Your AGENTS.md or CLAUDE.md is read and composed with them — see Configuration.

Step 6 is the slow one — about 30 seconds the first time, cached afterwards. init is not finished until omh new <harness> works, so it builds the image rather than deferring it to your first launch.

Step 3 reads your host only to learn which harness you prefer. The harness that runs is the one inside the sandbox, which is a different installation.

Log in

Section titled “Log in”
Terminal window
$ omh auth claude --name personal

This runs the harness’s own login flow — the same /login you would use normally — and captures the result into ~/.omh/creds/claude/personal/. You do this once per harness per account. See Accounts for several logins, and for why capture is keyed by harness rather than by provider.

Run

Section titled “Run”
Terminal window
$ omh new claude

You now have a container holding a git worktree on its own branch, with your profile mounted where Claude Code actually reads it. Your checkout is not mounted and the agent cannot reach it.

Terminal window
$ omh s01 diff              # what the agent changed
$ omh s01 commit -m "..."   # commit it onto the session branch
$ omh s01 push fix/thing    # push it to origin under a name a reviewer can read
$ omh s01 attach            # open the same session in your editor
$ omh graph                 # browse the codebase as a graph

Those run on the host, against the worktree you never have to visit. The agent cannot run them itself: the sandbox has a repository of its own but no way to reach yours, and it is told so rather than left to discover it.

Closing your terminal does not kill the agent — omh s01 resume puts you back in the session you left, running the harness it ran. See Sessions.

Verify it worked

Section titled “Verify it worked”

Do not trust the fact that it started.

Terminal window
$ omh doctor

doctor launches the real image with the real mounts and inspects the paths the harness actually reads. It is the only thing in the project that can prove an adapter is correct — a passing unit suite cannot, and Troubleshooting explains why in more detail than you probably want until the first time it matters.

Derive, never interrogate

Section titled “Derive, never interrogate”

Every question init could ask is hassle omh exists to remove, and most answers are already lying around: manifests name the stack, git log names what you work on, the README names the project. Derived facts also refresh when the repo changes, instead of going stale in a config file nobody revisits.

A question earns its place only if it is not derivable, actionable (omh does something different with the answer), and answerable well right now. “What is your job” fails all three.

The strongest permitted form is derive, then confirm — state the hypothesis and make it correctable:

! 2 stacks detected; hooks were written for all of them.
  drop the ones you do not want: .omh/hooks/

That is not a questionnaire. init still decided; it just showed its work.

Next

Section titled “Next”