aequitas-labs 开源 lobstah：面向编码智能体的监督框架

Nobody stares at the water.

Harness-agnostic, token-efficient supervision framework for coding agents.

You were promised agents that do the work. Somehow, watching them became the work: which one is stuck, which one is waiting on an answer nobody saw, which one died forty minutes ago. Watching is why you run two agents instead of ten.

A trap doesn't fish faster for being watched, and an agent doesn't code faster either. You lob bait into a trap and walk away. Each dispatch runs in its own git worktree; the daemon tells a dead process from a wedged one and recovers each; status and evidence land on disk. Supervision costs nothing — no tokens, no attention — so the whole fleet fits in one conversation, and your agents just bring home the lobstahs.

Which one? 🧭

As a background router, lobstah takes work you (or a tracker) lob in, runs supervised workers in their own worktrees, pings you when something needs you, and brings PRs home with no session open. As the lobstah man, one interactive Claude Code or Codex session takes the helm and runs that same fleet from a conversation, woken by the plugin's hooks instead of by you. Both sit on the same daemon, so start with the router and add a helm whenever you like.

Requirements 📋

• Node 20+, git, pnpm
• An authenticated harness CLI: claude (Claude Code) and/or Codex. Lobstah never handles harness login — you authenticate your own CLI; lobstah invokes it.

Quickstart: the background router 🪝

Hand lobstah a brief and go do something else.

Install

npm i -g lobstah             # or from source / a standalone binary: see Install below

Configure

lobstah init --scan ~/src    # ~/.lobstah + a [repos.*] block per repo found
                             # (bare `init` writes an example config instead;
                             #  `lobstah repos add <path>` appends one repo)
$EDITOR ~/.lobstah/config.toml
lobstah doctor               # binaries, config, repos, harnesses, heartbeat

notifyCommand = "ntfy pub my-topic \"$LOBSTAH_VERB $LOBSTAH_ID: $LOBSTAH_NOTE\""

[repos.myapp]
path  = "~/src/myapp"
trunk = "main"
setup = ["pnpm install"]     # runs in each fresh worktree

notifyCommand is how the router reaches you: the daemon runs it on needs-decision, blocked, done, and failed, with no model in the loop. Every key, with defaults: docs/configuration.md. The GitHub App permissions lobstah needs (Checks read, Pull requests and Contents read and write): docs/github.md.

Run

lobstah daemon install       # launchd agent / systemd user unit — survives
                             # reboots, restarts on crash (`daemon &` for a try)
lobstah pet install          # macOS: a desktop lobster walks questions to you
lobstah dispatch --repo myapp --brief ./brief.md

Want work to arrive on its own? lobstah pick install runs tracker pickup as a service: Linear and GitHub issues assigned to its configured identity become dispatches, and status streams back as comments. docs/pickup.md

See it

The lobstah man skill brings up the glass and prints its URL. lobstah man helm alone does not.

lobstah glass                # the spyglass: a live localhost page (port 4949)
lobstah ls                   # or the same from the terminal
lobstah catch <uuid>         # the evidence: branch, commits, PR, session

Quickstart: the lobstah man 🦞

One session holds the helm. You talk to it; it runs the fleet. The skill runs the lobstah commands.

Install

npm i -g lobstah             # the plugin wires hooks to the CLI; it doesn't bundle it
lobstah init --scan ~/src    # same repos, same config as the router
lobstah daemon install       # the helm dispatches; the daemon supervises

Then install the lobstah plugin for your harness (Claude Code · Codex) and open a new session.

Run

Open a new session in the repo (or any folder) with the plugin installed.

/lobstah:man                      # Claude Code
$lobstah:man                      # Codex

Or just say "Lobstah man, take the helm."

The skill signs on, arms the watcher when the Stop hook asks, and stays woken.

Then just talk: "dispatch a fix for the flaky login test in myapp." The helm writes a standalone brief, dispatches it, answers workers' questions, and brings you the catch.

Use /lobstah:trap in Claude Code or $lobstah:trap in Codex to turn another live session into a worker. The skill runs lobstah soak, which creates a linked worktree when the session is in a repo's primary checkout; the helm addresses bait to its wt:<trap> address, and /lobstah:stow ($lobstah:stow in Codex) signs it off. /lobstah:relieve ($lobstah:relieve) steps down from the helm.

Harness specifics: Claude Code · Codex. The full pattern (charter, grounds, the three tiers of getting woken, traps) is in docs/man.md.

Install ⚓

npm i -g lobstah

Or from source:

git clone https://github.com/aequitas-labs/lobstah
cd lobstah
pnpm install && pnpm build
ln -s "$PWD/bin/lobstah" /usr/local/bin/lobstah   # Windows: add .\bin to PATH

No Node on the box? Standalone binaries (bun-compiled) ship with every release for macOS/Linux/Windows:

curl -fsSL -o /usr/local/bin/lobstah \
  https://github.com/aequitas-labs/lobstah/releases/latest/download/lobstah-darwin-arm64
chmod +x /usr/local/bin/lobstah

The binary drives harnesses through their CLIs instead of the bundled SDKs: codex workers run fully Node-free; claude workers still need the (Node-based) claude CLI on the host.

Upgrade

npm i -g lobstah
lobstah daemon restart        # waits for the new heartbeat; refused while
                              # dispatches are active (--force overrides)
lobstah glass restart         # the glass service, or a detached glass
lobstah pick restart          # only if you run pick as a service

Then update the harness plugin: /plugin update lobstah@lobstah in Claude Code, or codex plugin marketplace upgrade lobstah && codex plugin add lobstah@lobstah in Codex. lobstah daemon status shows the running daemon's version, pid, and heartbeat age. lobstah doctor shows a warning when a plugin version differs from the CLI's.

Watch, steer, take over 🔭

lobstah ls                            # queue, active, recent done
lobstah status <uuid>                 # reconciled state + last note
lobstah logs <uuid> --follow          # normalized event stream
lobstah send <uuid> "also update the docs"   # delivered between turns
lobstah attach <uuid>                 # open the agent's own session in its worktree
lobstah swap <uuid> --harness codex   # hand an active dispatch to a fresh session
lobstah catch <uuid>                  # the evidence: branch, commits, PR, session
lobstah cancel <uuid>
lobstah cull --apply                  # sweep aged results and orphaned worktrees
lobstah man tend                      # the whole string: fleet verdict, waiting
                                      # questions, each item's chain + PR + gate
lobstah watch add ci:1234 --check 'my-ci events --since {cursor} --json'
                                      # stand watch on anything external — its
                                      # events wake you like a dispatch would
lobstah soak                          # volunteer this worktree's session as a
                                      # worker: sign-on anchors its wt:<trap>
                                      # address; `dispatch --for wt:<trap>` bait
                                      # waits for it, never a headless spawn

Prefer the water? 🌊 set --bait, buoys, and buoy alias dispatch, ls, and status.

Dispatches report six verbs: working, needs-decision, blocked, paused, done, failed. The write path rejects anything else. done means the brief is fulfilled. Merging is never the dispatch's job.

Everything lives under $LOBSTAH_HOME (default ~/.lobstah). To run more instances, use more homes. One daemon per home, enforced.

When something needs you 🛎️

Set one config line — notifyCommand = "ntfy pub my-topic ..." — and the daemon pings you on needs-decision, blocked, done, and failed. No model in the loop. Driving lobstah from an agent session instead? lobstah man prints the lobstah man's manual. man wait blocks until a dispatch needs attention, and unanswered questions re-fire until answered. man helm signs one session on as the orchestrator for its grounds, and man report prints the delta since the last acknowledged report. lobstah glass serves it all as a live localhost page — the spyglass. man init installs a Claude Code Stop hook that parks the session on the fleet and continues the turn the moment something needs it.

Add-ons 🎣

• Desktop pet — walks attention across your screen; run lobstah pet install on macOS. Install guide
• Tracker pickup — lobstah pick polls Linear and GitHub outbound (no webhooks, no tunnel), dispatches assigned work, streams status back as comments, forwards replies into the running dispatch, reconciles drift, and optionally merges approved PRs. GitHub pickup spans every repo you mark pickup = true; lobstah pick install runs it as a service. docs/pickup.md
• Claude Code + Codex plugins — the lobstah man as a one-step install: the hook wiring (session brief, Stop-hook park, clean stow) and the same four skills in both harnesses (man, trap, stow, relieve), no settings surgery. This repo doubles as the plugin marketplace for both agent registries — install steps per harness are in docs/harness/claude-code.md and docs/harness/codex.md. The park stays inert until a directory opts in with a .lobstah-man file or the session soaks. Codex hooks need Codex v0.114+ and a one-time trust review. Plugin versions track the CLI (plugin 0.5.x goes with lobstah 0.5.x); lobstah doctor and the session brief say when the installed plugin is behind. Details per harness: plugins/claude-code · plugins/codex.
• OpenClaw plugin — gives fleet agents lobstah_dispatch / lobstah_status / lobstah_send / lobstah_cancel tools and operators a /lobstah command. docs/openclaw.md
• The lobstah man — one interactive agent session that dispatches, supervises, and hands you outcomes, woken by the lobstah man commands. Harness-agnostic: hold the helm from Claude Code, Codex, or anything with a terminal — the CLI is the contract, and workers mix harnesses per dispatch. docs/man.md

How it holds together 🧭

CLI / pick / OpenClaw plugin / anything ──writes──>  ~/.lobstah/queue/
                                                           │ claim (atomic rename)
daemon ──spawn──> runner (one per dispatch) ──SDK──> harness CLI
   │                  │
   │                  └── worktree per dispatch · status/evidence/events on disk
   └── dead/wedged classification · bounded restart ladder · zero tokens

Design: docs/design.md. Every verb, verdict, and gate in one place: docs/vocabulary.md. Verified by CI on Linux and Windows, by live end-to-end runs on both harnesses, and by fault-injection drills. A SIGKILL'd runner respawns and completes. A SIGSTOP'd one is classified wedged, killed cleanly, and recovers with a nudge.

Telemetry 📊

lobstah shares an anonymous daily count of its work, on by default. Once per UTC day the daemon sends catches: {today, total} for the UTC day and all-time, plus up to 100 traps: [{name, today, harness, model, config}] entries with automatically generated names and recorded provenance. Custom names (--name) and older names with unknown provenance stay local; their catches remain in the totals. Names are not hashed. A helm snapshot and up to 100 headless byWorker count buckets include harness, catalog-only model id, and nullable reasoning effort/permission-mode enums. Unknown observations stay null; custom or unrecognised model ids become other. No arbitrary config is sent. The payload also includes the lobstah version, OS family, CPU architecture, the UTC date, and a random install id made on your machine. It never sends repository names or paths, code, briefs, session ids, PR URLs, hostnames, or usernames. Hooks never send anything, and nothing is sent until a one-time notice has been shown in your terminal. The counts feed a project-wide 🦞 N badge. Per-install rows are deleted after 90 days, as are per-trap and worker/config rows; retained daily totals have only counts, including harness/model aggregates, no names or config.

• lobstah telemetry show prints the exact JSON that would be sent.
• lobstah telemetry status shows whether it is on and why.
• Turn it off with any one of: lobstah telemetry disable, [telemetry] share = false in ~/.lobstah/config.toml, LOBSTAH_TELEMETRY=0, DO_NOT_TRACK=1, or CI set.

No release sends anything yet: the endpoint is not set. Everything about it, including who receives it and how long it is kept, is in PRIVACY.md.

Non-goals

No webhooks or inbound listeners, no merge decisions in core, no tracker vocabulary in core, no hosted service (the one exception is the small anonymous telemetry endpoint in services/telemetry, which you can turn off).

License

MIT