把 oberth 放进 agent 的循环
接口只有 CLI 和 --json。集成就是在工具自己的 setup、run、cleanup 槽位里调用它——不替你装 hooks、不注册 MCP server、不代你写任何配置。
三个调用时机
工具提供生命周期槽位时，用同样的三次调用：创建之后启动，运行期间读取，结束时停止。
# 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/checkoutagent 开局的三次读取
oberth --help 末尾有一段 For agents，给的是阅读模式，不是新命令。三次读取足够让会话定位自己，不用去拼 ps、lsof 或 tail。
oberth status --json --brief
oberth up --wait --json
oberth logs <service> --once --json --run current --first-error- 先
status：声明了什么、跑着什么、哪个端口、健康过没过、最近为什么失败。 - 确实应该有东西在跑时才
up --wait；它等真实就绪，而不是睡一会儿。 - 失败之后才
logs --run current --first-error；它指向一行，不给猜测。
接入配方
工具自己的配置由用户写。项目级配置可以随仓库提交；产品不分发集成代码，也不写任何工具配置。
| 工具 | 槽位 | 放什么 |
|---|---|---|
| Cursor | .cursor/worktrees.json → setup-worktree-unix | up --wait；Cursor 没有 teardown hook，删除前要自己跑 down --worktree。 |
| Claude Code | WorktreeCreate / WorktreeRemove hooks，或外层 wrapper | up --wait；down --worktree。接管创建会替换 Claude 自己的 worktree 行为。 |
| Codex | 外层 wrapper，或桌面应用的 Local environments setup | up --wait；清理仍要在删除前跑 down。 |
| Conductor | .conductor/settings.toml 的 setup 与 archive 槽位 | up --wait；down --worktree。 |
最可移植的集成是 AGENTS.md 或 CLAUDE.md 里的一段话。下面是精简版；包含 machine: / workspace: 边界的完整段落见 docs/integrations.md。引擎不会替你安装它。
## 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.容易踩的坑
- hook 通常不加载你的 shell rc。用
oberth的绝对路径，或显式设置PATH；node、npm、python3也必须能找到。 - workspace 根不一定是 Git checkout 根。先
cd "$(git rev-parse --show-toplevel)"，并把同一个根传给down --worktree。 - 不要给
port: auto的服务硬编码PORT：服务自己的env: PORT会覆盖注入值，让等待盯着错的端口。 - 优先打开框架的严格端口选项。悄悄换端口的框架会把冲突拖成迟到的
ready_timeout。 - 沙箱里观察可能是盲的。不要在循环里反复重开；跟着
observation_*的 hint 换到外面重试。
skill 是独立产品
option-berth-skill 教 agent 同一套 CLI 和 --json 形状。它单独安装，例如 npx skills add SheathedSharp/option-berth-skill -g。引擎不安装、不更新、也不依赖它；装不装是用户的决定。