Stop guessingwhat's running.
oberth is the runtime facts layer for Git worktrees: one manifest says what should run, one command says whether it really is running, and why not. People and coding agents read the same facts.
oberth status · example project hello-worktree
hello-worktree · main
api running :21730 health 200
worker running no port
2 services · manifest oberth.yamlDone is the metric.
80 real agent runs: 8 ten-service stacks × 2 setups × 5 repeats, one agent and one binary. Left column is with oberth; right is the agent alone.
8/8 scenarios needed fewer turns; out-of-bounds moves: 0/0.
| Metric | With oberth | Agent alone |
|---|---|---|
| Tasks completed | 40/40100% | 29/4072.5% |
| Median turns | 5P95 10 | 9P95 17 |
| Median time | 45s | 69s |
Measured 2026-11-04. One agent, one model, internal fixtures; 5 runs per cell, so p95 is directional. This run Method and raw data
Four worktrees, four guesses.
A port guessed 3000 in use, a failure buried in logs exit 1, and no one can say which service is actually running worker · no port.
You confirm. The engine answers.
From confirming the manifest to starting services and reading the facts back, there is one chain.
You confirm what runs.
A person confirms the manifest; an agent may only draft it. A run belongs to the worktree that started it.
Start in dependency order.
up runs prepare first, then starts services in depends_on order and waits for real readiness.
See three separate facts.
Process, listener and health are separate facts. No port does not mean not running.
Return to the failure.
logs reads the service's own output and exit reason, not a reassembled system command.
oberth.yaml · example project hello-worktree
name: hello-worktree
services:
- name: api
cmd: python3 -u api.py
port: auto
health: /health
- name: worker
cmd: python3 -u worker.py
depends_on: [api]
env:
API_URL: ${api.url}oberth up --wait · example project hello-worktree
api started :21730 ready
worker started no portoberth status · example project hello-worktree
api running :21730 health 200
worker running no portoberth logs worker --once · example project hello-worktree
worker: API health=200
worker: API health=200
worker: API health=200Six commands, one loop.
From status to logs, people read tables and agents read --json; the same contract, with no second set to remember.
oberth status --jsonread-onlyWhat is true now: declaration, runtime, ports and the last exit.oberth up --waitstartStart services in depends_on order and wait for real readiness.oberth logslogsReturn to the failure scene and read the service's own output.oberth downstopStop only this worktree's services, without touching another checkout.oberth workplacerecordKeep the commands and tasks run here on the worktree for the next session.oberth doctorcheckCheck the environment, manifest and run conditions without calling unknown a success.
No matching command. Clear the field to see them all.
One service, four facts.
Not a machine-wide port list; it answers only for the services this worktree declares.
Process
running
A worker with no port is still confirmed by its run record.
Port
21730 auto
An auto port is assigned by the engine and shown with its service.
Health
200 /health
A live process is not the same as a healthy one.
Exit
none
A failure leaves a reason, an exit code and logs.
No port
worker · running
No listener does not mean not running.
Install the engine.
Build from source, or download the archive for your platform. Archives contain only the engine and adapter.
Building installs nothing and starts no daily service. mage install writes to the install directory and changes PATH.
Build from source
git clone https://github.com/SheathedSharp/option-berth.git
cd option-berth
brew install go mage
mage buildEngine
./bin/oberth version --jsonInstall with one command
The script resolves the latest release, downloads the archive for this platform, verifies SHA256, and installs into ~/.local/bin; pin a version with --version.
curl -fsSL https://raw.githubusercontent.com/SheathedSharp/option-berth/main/install.sh | shOn Windows use PowerShell: irm .../install.ps1 | iex. Full service scenarios are verified on macOS/Linux; Windows has native build and smoke checks, not full lifecycle coverage.
See the latest engine release Install, upgrade and uninstallThe boundaries come first.
Does it have a graphical interface?
The interface is the separate macOS client. It is not in this repository and does not ship with the engine.
Does it take over every port on the machine?
No. It answers only for the current worktree's declared services; machine: dependencies stay read-only.
Does it write to my Git repository?
Product Git actions are read-only. A person confirms the manifest; an agent may draft it but cannot adopt it for you.
Does no port mean it is not running?
No. A portless worker is observed through its run record; process, listener and health are separate facts.
How complete is Windows support?
There are native builds, smoke tests and some fact/persistence checks. Full service scenarios are verified only on macOS/Linux.
Does it need a model account or the cloud?
No. The engine runs locally, contains no model inference and has no cloud sync.
How does a coding agent learn to use it?
The skill is a separate repository. Install it for the agents already on your machine with npx skills add SheathedSharp/option-berth-skill -g, or through the Claude Code plugin marketplace. The engine does not install it for you.
Can I use it with Conductor, Cursor, Claude Code or Codex?
Yes. Call oberth from their own setup/cleanup scripts or an outer wrapper; the engine installs no hooks and edits none of their configuration. Recipes are linked in the footer under “Integrations”.
A berth for your next checkout.
The engine, the macOS client and the coding-agent skill release on their own schedules and share one chain of facts.