The option-berth guide
oberth keeps one answer per Git worktree: what should run, whether it really is running, and why not. A person reads a table; a coding agent reads the same command with --json. This book teaches the chain behind both.
Four checkouts, four guesses
Git worktrees solved parallel code, not parallel runtime. Four checkouts of one repository share a port range, a database name and a shell history, so every session re-derives the same three facts — and derives them slightly differently each time.
oberth writes those facts once, in one order, and lets every reader read the same thing: worktree → manifest → service → run → runtime facts. Nothing downstream re-invents what upstream already published.
One chain, five stations
| Station | The question it settles | What it may not do |
|---|---|---|
| Worktree | Which checkout does a run belong to? | Belong to a checkout it did not start in. |
| Manifest | What should run, on which port, after what? | Be guessed from a running process, or adopted by a model. |
| Service | Which declaration starts, in which order, on which address? | Start a dependent service before its dependency is ready. |
| Run | pid, start, end, exit code, log path. | Count as listening because the process exists. |
| Runtime facts | Alive, listening, healthy, and why it ended. | Turn a table it could not read into “not running”. |
The chain of facts follows the five stations in order, one chapter section each.
The loop you actually run
Five commands cover a working day. Each replaces a shell one-liner that had to be re-invented per checkout.
| You want to | oberth | The shell answer it replaces |
|---|---|---|
| Declare the stack | oberth init | a README paragraph and a script nobody updates |
| Start and wait for readiness | oberth up --wait | npm run dev &, sleep, then curl until it answers |
| Know what should run, and what does | oberth status | read oberth.yaml, then ps, lsof and tail against it |
| Read a failure | oberth logs api --once | tail the right file and guess the exit code |
| Stop this checkout only | oberth down | kill a pid assembled from ps |
hello-worktree · main
api running :21730 health 200
worker running no port
2 services · manifest oberth.yamlHow to read this book
- First time here. Install oberth, then follow Your first worktree: one example project, five commands, from an empty checkout to a clean stop.
- You already run things. Read the chain of facts and worktrees and runs, then use the command chapters as you need them.
- You are wiring an agent. Start at Facts as JSON, then coding agents for the three moments to call oberth.
Two readers, one interface
There is no second interface, no MCP server and no model in the core. The CLI is the contract; --json is the same contract in a machine shape.
oberth status --json --brief
oberth up --wait --json
oberth logs api --once --json --run current --first-errorllms.txt lists this book for machines, and llms-full.txt carries every chapter as plain text.