Put oberth inside the agent's loop

The interface is the CLI and --json. Integration means calling it from the tool's own setup, run and cleanup slots — no hooks installed for you, no MCP server, no configuration written on your behalf.

Three moments

Where a tool offers lifecycle slots, use the same three calls: start after creation, read while running, stop at the end.

the integration, in three calls

# after the checkout is created
oberth up --wait --json
# while it runs
oberth status --json --brief
# when the work ends
oberth down --worktree /absolute/path/to/checkout

The reads an agent opens with

oberth --help ends with a For agents section that gives a reading pattern, not commands. The three reads are enough for a session to orient itself without assembling ps, lsof or tail.

the opening pattern

oberth status --json --brief
oberth up --wait --json
oberth logs <service> --once --json --run current --first-error

status first: what is declared, what runs, which port, whether health passed, why it last failed.
up --wait only when something should be running; it waits for real readiness instead of a sleep.
logs --run current --first-error only after a failure; it points at a line, not a guess.

Recipes

The tool's own configuration is written by the user. Project-level configuration can be committed; the product distributes no integration code and writes no tool configuration.

Where to call oberth in common tools
Tool	Slot	What to put there
Cursor	`.cursor/worktrees.json` → `setup-worktree-unix`	`up --wait`; there is no teardown hook, so run `down --worktree` before deletion.
Claude Code	`WorktreeCreate` / `WorktreeRemove` hooks, or an outer wrapper	`up --wait`; `down --worktree`. Taking over creation replaces Claude's own worktree behavior.
Codex	an outer wrapper, or the desktop app's Local environments setup	`up --wait`; cleanup still runs `down` before deletion.
Conductor	`.conductor/settings.toml` setup and archive slots	`up --wait`; `down --worktree`.

The most portable integration is a paragraph in AGENTS.md or CLAUDE.md. This is a compact version; the full section, including the machine: / workspace: boundary, is in docs/integrations.md. The engine does not install it.

AGENTS.md · local services

## Local services

The services in this worktree are managed by option-berth (`oberth`).
Before starting or troubleshooting, read the facts with it first.

- Run `oberth status --json` before guessing ports or digging through `ps`.
- Start with `oberth up --wait --json`; do not reimplement dependency order.
- On failure read `oberth logs <service> --once --json`; do not substitute a timeout for the reason.
- When `observation.state` is not `observable`, say you cannot see the listener and follow the hint.
- Stop this checkout with `oberth down`; never kill by a guessed pid.

Pitfalls

Hooks often do not load your shell rc. Use the absolute path to oberth, or set PATH explicitly; node, npm and python3 must be on it too.
The workspace root is not always the Git checkout root. cd "$(git rev-parse --show-toplevel)" first, and pass the same root to down --worktree.
Do not hardcode PORT for a port: auto service: a service's own env: PORT overrides the injected value and makes the wait watch the wrong port.
Prefer the framework's strict-port option. A framework that quietly switches ports turns a conflict into a late ready_timeout.
In a sandbox, observation may be blind. Do not retry the same start in a loop; follow the observation_* hint and retry outside it.

The skill is a separate product

option-berth-skill teaches an agent the same CLI and --json shapes. It is installed separately, for example with npx skills add SheathedSharp/option-berth-skill -g. The engine does not install, update or require it; whether to install it is the user's decision.

Edit this page