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**
**Configure**
[hooks.notify] is how the router reaches you: the daemon runs its command
on needs-decision, blocked, paused, 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**
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.
Quickstart: the lobstah man 🦞
One session holds the helm. You talk to it; it runs the fleet. The skill runs
the lobstah commands.
**Install**
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.
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: 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 ⚓
Or from source:
No Node on the box? Standalone binaries (bun-compiled) ship with every
release for
macOS/Linux/Windows:
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
Then update the harness plugin: /plugin update lobstah@lobstah in Claude
Code, or codex plugin marketplace upgrade lobstah && codex plugin add