lobster names one tool four ways and publishes five files

Four names for one tool and two front doors

The repository is openclaw/lobster. The published package is @clawdbot/lobster. The executable is lobster. And the bin map registers two further entry points, clawd.invoke and openclaw.invoke, so one manifest carries two spellings of the parent project's name in the same object, neither of which is the scope it publishes under. A reader who has met the word clawd in one place and openclaw in another has to work out for themselves that they refer to the same thing. The manifest's homepage field points at the GitHub readme while the project's declared homepage is a documentation site, so there are two front doors and only one of them travels inside the package. None of this is broken. All of it is friction, and it lands in the places where a name is written once and then copied forever: an install line, a pinned version in CI, an issue link, a shell alias.

The published tarball is five entries long

The files array is bin, dist/src, README.md, LICENSE and VISION.md. Everything else at the root stays behind: src, test, docs, both tsconfig files, the formatter and linter configs, the lockfile, the workspace file, AGENTS.md, CHANGELOG.md, the .agents directory and .crabbox.yaml. The build script runs on prepack, so what arrives is compiled output rather than TypeScript, which is the right call for a runtime whose quick start points you at a compiled entrypoint. The cost is that a consumer receives three documents and no tests, no lint rules and no changelog, so the two questions a package normally answers in place, which version changed this behaviour and which rule have I broken, become questions about a repository instead. The excluded docs directory is the sharpest omission: it exists in the checkout and is deliberately kept out of the tarball.

Quick start runs it by path, later examples assume the path

The quick start is a contributor checklist dressed as an install guide. It asks for Node.js 22 or newer and the pnpm version pinned in package.json, then runs pnpm install --frozen-lockfile, pnpm build, pnpm test and pnpm lint before showing node ./bin/lobster.js --help. Every command is addressed by path from inside the checkout. Further on, the same page switches convention without comment, calling lobster by name:

lobster run path/to/workflow.lobster
lobster run --file path/to/workflow.lobster --args-json '{"tag":"family"}'

Nothing in the six-step sequence puts a binary named lobster on your path, so those later lines only work after installing the package or editing your shell. Two addressing conventions in one document, with the one that needs an extra step demonstrated first.

pnpm clean deletes dist, which is where the CLI lives

The clean script removes the dist directory recursively, and the build script runs clean before compiling against the build tsconfig. The test script runs clean as well, then compiles against a different tsconfig, then asserts that dist/test exists before running the test files out of dist. Two configurations, two guarantees, and both commands begin by deleting the single directory the runtime reads from. bin/lobster.js executes the compiled entrypoint in dist, and the page tells you to build after changing source files, so a Lobster process running when the suite starts is a process whose files are being removed underneath it. The scripts do nothing to keep the two apart. The revealing detail is the extra check: the test script verifies that dist/test exists before invoking the test runner, and the build script has no equivalent. Whichever path can produce a missing directory, one of them was guarded and the other was not.

The output cap is one string, per stream, and opt-in

Captured stdout and stderr are unlimited by default. LOBSTER_MAX_OUTPUT_BYTES opts into a byte limit applied per stream and per process. Unset or empty means unlimited, while zero, negative, fractional and non-numeric values are rejected before a process starts, so misconfiguration arrives as an error rather than as a truncated stream. The scope is deliberately wide: one variable governs CLI exec, workflow shell steps, SDK exec and shell calls, GitHub recipes and Gog commands.

LOBSTER_MAX_OUTPUT_BYTES=1048576 lobster run --mode tool 'exec my-command'

Values exactly at the limit succeed, and overflow terminates the process tree and returns an error with no partial output, so a capped run either has its whole stream or has failed. On POSIX, capped calls own a process group, which is what stops a background producer from holding the pipe open after the cap trips. One more ceiling sits above this one and is not yours to move: the 10 MiB limit openclaw.agent already applies, which an opted-in limit can only lower.

Cancellation kills its own children and asks yours

An AbortSignal passed to new Lobster cancels SDK exec stages, including the shell form, and the signal is retained by clone and forwarded when a pipeline resumes. Aborting terminates the running child process tree before run or resume returns, and the result carries the abort reason. A signal that is already aborted stops the command from starting at all. That is a full guarantee for anything Lobster spawns itself. For stages you wrote, the signal arrives as ctx.signal and the stage has to honour it. The GitHub recipes sit on the strong side of that line too: prMonitor and prMonitorNotify both accept a signal, aborting stops the GitHub CLI child, and a cancelled fetch neither updates the saved pull request snapshot nor emits a notification. That last clause is the one to remember, because not writing state on cancellation is what makes retrying safe afterwards.

A retried loop restarts at the first item

Per-step policy comes from retry, timeout_ms and on_error, and it behaves the same whether a step runs once or inside a for_each. On a loop those policies cover the whole thing rather than each pass: every attempt is given one timeout budget, batch pauses included, and a retry restarts at the first item instead of the failed one. Items that already completed can run again, so the guidance is to enable loop retries only for work that is safe to repeat. A cost_limit stop or an attempted OpenClaw dispatch prevents retries altogether. The result is a delivery guarantee of at-least-once per loop rather than per item, which is the right default for watching a pull request and the wrong one for anything that spends money twice or asks a person twice.

Three places for a gate, and a renderer that changes at the top

An approval gate can be written as an approval step inside a workflow file, as the approve command with a TTY prompt or with --emit for OpenClaw integration, or as a named workflow invoked with run --mode tool, which is the shape the opening example takes, where OpenClaw shows the gate to a person and resumes with their decision. The preference is stated once, in a single sentence: if you need a human checkpoint before an LLM call, use a dedicated approval step in the workflow file rather than approve inside a nested pipeline. Easy to miss precisely because it appears once. Beside it is a second rule worth reading twice. In a top-level tool-mode pipeline, including resumes and the core tool API, the json and table stages preserve typed items inside the single JSON envelope instead of writing terminal output, while human-mode rendering and rendering captured within workflow-file steps stay as they were. The same script yields different bytes depending on where it starts.

Editorial conclusion

Adopt it for the parts that are specified precisely, because there are not many projects that tell you what a cancelled fetch does to its own saved state, or that a retried loop restarts at the first item instead of the failed one. Those two sentences save more debugging than the naming and packaging do cost, and the naming and packaging are the only parts a newcomer meets first. Before writing anything against it, install the published package rather than building the checkout, so the binary exists on your path, and read the output cap and the loop retry rules as design constraints rather than as options. What to check in your own setup is narrower than it looks: whether the steps you want to retry are safe to repeat, and whether your custom stages honour the cancellation signal they are handed, since Lobster will not enforce that for you.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes