Lobster: A Typed Workflow Shell That Gives OpenClaw Agents Reusable Pipelines

The Problem Lobster Solves

Lobster targets a specific inefficiency: an AI agent like OpenClaw re-plans every step of a routine task each time it runs. Checking a pull request for changes, summarizing a diff, or waiting for a human approval are not novel operations, yet the agent spends tokens and time re-deriving them. Lobster packages those operations into named workflows that the agent invokes in a single call, for example workflows.run --name github.pr.monitor. The output is a structured JSON snapshot, so the agent gets a deterministic result without re-planning. The intended user is someone building automations on OpenClaw, or any agent host, who wants repeatable, resumable pipelines that do not depend on the agent's improvisation.

Typed Pipelines Instead of Text Pipes

The core design choice is that Lobster pipelines pass objects and arrays, not raw text. The quick start example shows exec --json --shell 'echo [1,2,3]' | where '0>=0' | json, where where operates on a JSON array. This is a deliberate departure from Unix-style text piping. The README states the goal as 'Typed pipelines (objects/arrays), not text pipes.' That means each stage can reference $step.stdout or $step.json from a previous step, and the data shape is known ahead of time. For an agent, that reduces parsing errors and makes the output directly usable. It also means the workflow file reads like a small script with explicit data flow, which is easier to debug than a chain of shell commands.

Workflow Files: Steps, Gates, and Data Flow

A workflow file is YAML with a name, optional args, and a list of steps. Each step can be a run or command for shell execution, a pipeline for native stages like llm.invoke, or an approval for a human checkpoint. The example jacket-advice workflow shows the pattern: a fetch step runs weather --json ${location}, a confirm step asks 'Want jacket advice from the LLM?' and feeds $fetch.json to the next step, and an advice step calls llm.invoke with a prompt and the same stdin. The when: $confirm.approved condition gates the LLM call. Data flows through stdin references, and steps share the same args/env/results model whether they are shell or pipeline. This uniformity is a strength: you can mix a curl call with an LLM invocation and pass data between them without conversion.

Approval Gates and Identity Constraints

Approval is not just a yes/no prompt. Lobster supports identity-aware gates. A workflow step can set approval.required_approver to demand an exact approver id, or approval.require_different_approver to ensure the approver differs from the initiator. The initiator can be set with approval.initiated_by or via the LOBSTER_APPROVAL_INITIATED_BY environment variable, and the approver identity comes from LOBSTER_APPROVAL_APPROVED_BY at resume time. This is a meaningful control for automations that touch sensitive operations, like merging a PR or spending money. The README also advises using a dedicated approval step in the workflow file rather than nesting approve inside a pipeline, which keeps the gate visible in the graph. For CLI use, approve can emit a token with --emit for OpenClaw integration, though the details of that token flow are not fully specified.

Resumability and the requestInput Mechanism

A notable mechanism is ctx.requestInput, which lets a pipeline command pause and wait for a structured response. The command can specify a prompt, responseSchema, defaults, subject, and suspendedState. On resume, the command is re-run from the start, so the README warns that commands must be idempotent until requestInput returns. This is a real constraint: if your command has side effects before the pause, re-running it could duplicate work. The README also notes that array-backed command input is snapshotted with bounds for replay, but lazy stream input is not buffered and requires the command to supply a compact JSON suspendedState. That means streaming data sources are a weak spot. If you plan to feed a live stream into a workflow, you need to handle state manually, and the documentation does not give a concrete example of doing so.

LLM Integration and Provider Resolution

Lobster includes native LLM steps through llm.invoke. Providers are resolved in order: --provider flag, LOBSTER_LLM_PROVIDER, then auto-detection from the environment. The built-in providers are openclaw (via OPENCLAW_URL and OPENCLAW_TOKEN), pi (via LOBSTER_PI_LLM_ADAPTER_URL), and http (via LOBSTER_LLM_ADAPTER_URL). A host can supply custom adapters through ctx.llmAdapter, but the README truncates before explaining how. For an OpenClaw user, the openclaw provider is the obvious choice. For others, the http adapter suggests a generic endpoint, but there is no schema documented in the visible material. That is a gap: you can call an LLM, but you cannot be sure what request shape the http adapter expects without reading more source.

Visualizing Workflows Before Running

The lobster graph command lets you inspect a workflow's structure before execution. It supports four output formats: mermaid (default), dot, ascii, and terminal-friendly node/edge lists. The visualization includes each step as a node, data-flow edges from stdin references, conditional dependencies from when or condition expressions, and approval gates as diamond shapes in mermaid and dot. This is a practical debugging aid, especially for workflows with multiple branches. The ability to pass --args-json to graph means you can see the resolved graph for a specific set of arguments, which is useful because a when condition might change based on an arg value. The ascii format is handy for quick terminal checks without opening a renderer.

Getting Started and Maintenance Costs

Setup is straightforward from the repository: pnpm install, pnpm test, pnpm lint, then node ./bin/lobster.js --help. The doctor command checks the environment. The compiled entrypoint in dist/ is preferred when present, so you need to build before running from source. Workflows are invoked with lobster run --file path/to/workflow.lobster --args-json '{"tag":"family"}'. The project is MIT-licensed, which means you can embed it without copyleft obligations. Maintenance appears active, with releases on a monthly cadence (v2026.4.6, v2026.5.22, v2026.6.11). The test suite runs tsc and then tests against dist/, so type errors are caught early. The main upgrade cost is learning the workflow file schema and the requestInput idempotency rule. There is no mention of a plugin registry or package manager for sharing workflows, so you likely maintain them in your own repo.

Editorial conclusion

Adopt Lobster if you run OpenClaw or another agent that repeatedly performs multi-step tasks with deterministic steps and human checkpoints, and you want to cut token usage by packaging those steps into one call. Skip it if you need a general-purpose orchestrator with its own auth model, or if your workflows depend on streaming input that cannot be snapshotted. Before adopting, verify that your shell steps are idempotent until requestInput returns, since commands re-run on resume, and confirm your LLM provider is covered by one of the three built-in adapters or a custom ctx.llmAdapter. Lobster is MIT-licensed, actively released, and clearly scoped, but it is not a replacement for a full workflow engine.

Official sources

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