An OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.

OpenClaw (or any other AI agent) can use lobster as a workflow engine and avoid re-planning every step — saving tokens while improving determinism and resumability.

node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1152}'" [ { "kind": "github.pr.monitor", "repo": "openclaw/openclaw", "prNumber": 1152, "key": "github.pr:openclaw/openclaw#1152", "changed": false, "summary": { "changedFields": [], "changes": {} }, "prSnapshot": { "author": { "id": "MDQ6VXNlcjE0MzY4NTM=", "is_bot": false, "login": "vignesh07", "name": "Vignesh" }, "baseRefName": "main", "headRefName": "feat/lobster-plugin", "isDraft": false, "mergeable": "MERGEABLE", "number": 1152, "reviewDecision": "", "state": "OPEN", "title": "feat: Add optional lobster plugin tool (typed workflows, approvals/resume)", "updatedAt": "2026-01-18T20:16:56Z", "url": "https://github.com/openclaw/openclaw/pull/1152" } } ] 

 node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1200}'" [ { "kind": "github.pr.monitor", "repo": "openclaw/openclaw", "prNumber": 1200, "key": "github.pr:openclaw/openclaw#1200", "changed": true, "summary": { "changedFields": [ "number", "title", "url", "state", "isDraft", "mergeable", "reviewDecision", "updatedAt", "baseRefName", "headRefName" ], "changes": { "number": { "from": null, "to": 1200 }, "title": { "from": null, "to": "feat(tui): add syntax highlighting for code blocks" }, "url": { "from": null, "to": "https://github.com/openclaw/openclaw/pull/1200" }, "state": { "from": null, "to": "MERGED" }, "isDraft": { "from": null, "to": false }, "mergeable": { "from": null, "to": "UNKNOWN" }, "reviewDecision": { "from": null, "to": "" }, "updatedAt": { "from": null, "to": "2026-01-19T05:06:09Z" }, "baseRefName": { "from": null, "to": "main" }, "headRefName": { "from": null, "to": "feat/tui-syntax-highlighting" } } }, "prSnapshot": { "author": { "id": "MDQ6VXNlcjE0MzY4NTM=", "is_bot": false, "login": "vignesh07", "name": "Vignesh" }, "baseRefName": "main", "headRefName": "feat/tui-syntax-highlighting", "isDraft": false, "mergeable": "UNKNOWN", "number": 1200, "reviewDecision": "", "state": "MERGED", "title": "feat(tui): add syntax highlighting for code blocks", "updatedAt": "2026-01-19T05:06:09Z", "url": "https://github.com/openclaw/openclaw/pull/1200" } } ] 

• Typed pipelines (objects/arrays), not text pipes.
• Local-first execution.
• No new auth surface: Lobster must not own OAuth/tokens.
• Composable macros that OpenClaw (or any agent) can invoke in one step to save tokens.

From this folder:

• pnpm install
• pnpm test
• pnpm lint
• node ./bin/lobster.js --help
• node ./bin/lobster.js doctor
• node ./bin/lobster.js "exec --json --shell 'echo [1,2,3]' | where '0>=0' | json"

• pnpm test runs tsc and then executes tests against dist/.
• bin/lobster.js prefers the compiled entrypoint in dist/ when present.

• exec: run OS commands
• exec --stdin raw|json|jsonl: feed pipeline input into subprocess stdin
• where, pick, head: data shaping
• json, table: renderers
• approve: approval gate (TTY prompt or --emit for OpenClaw integration)

• OpenClaw integration: ship as an optional OpenClaw plugin tool.

Lobster workflow files are meant to read like small scripts:

• run: or command: for deterministic shell/CLI steps
• pipeline: for native Lobster stages like llm.invoke
• approval: for hard workflow gates between steps
• stdin: $step.stdout or stdin: $step.json to pass data forward

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

Example file:

name: jacket-advice args: location: default: Phoenix steps: - id: fetch run: weather --json ${location} - id: confirm approval: Want jacket advice from the LLM? stdin: $fetch.json - id: advice pipeline: >  llm.invoke --prompt "Given this weather data, should I wear a jacket?  Be concise and return JSON."  stdin: $fetch.json when: $confirm.approved

Notes:

• run: and command: are equivalent; run: is the preferred spelling for new files.
• pipeline: shares the same args/env/results model as shell steps, so later steps can still reference $step.stdout or $step.json.
• If you need a human checkpoint before an LLM call, use a dedicated approval: step in the workflow file rather than approve inside the nested pipeline.
• cwd, env, stdin, when, and condition work for both shell and pipeline steps.

Use llm.invoke from a native pipeline: step for model-backed work:

llm.invoke --prompt 'Summarize this diff' llm.invoke --provider openclaw --prompt 'Summarize this diff' llm.invoke --provider pi --prompt 'Summarize this diff'

Provider resolution order:

• --provider
• LOBSTER_LLM_PROVIDER
• auto-detect from environment

Built-in providers today:

• openclaw via OPENCLAW_URL / OPENCLAW_TOKEN
• pi via LOBSTER_PI_LLM_ADAPTER_URL (typically supplied by the Pi extension)
• http via LOBSTER_LLM_ADAPTER_URL

llm_task.invoke remains available as a backward-compatible alias for the OpenClaw provider.

Shell run: steps execute in your system shell, so OpenClaw tool calls there must be real executables.

If you install Lobster via npm/pnpm, it installs a small shim executable named:

• openclaw.invoke (preferred)
• clawd.invoke (alias)

These shims forward to the Lobster pipeline command of the same name.

Prereqs:

• OPENCLAW_URL points at a running OpenClaw gateway
• optionally OPENCLAW_TOKEN if auth is enabled

export OPENCLAW_URL=http://127.0.0.1:18789 # export OPENCLAW_TOKEN=...

In a workflow:

name: hello-world steps: - id: greeting run: >  openclaw.invoke --tool llm-task --action json --args-json '{"prompt":"Hello"}'

Use stdin: $stepId.stdout to pipe output from one step into the next.

${arg} substitution is a raw string replace into the shell command text.

For anything that may contain quotes, $, backticks, or newlines, prefer env vars:

• every resolved workflow arg is exposed as LOBSTER_ARG_<NAME> (uppercased, non-alnum → _)
• the full args object is also available as LOBSTER_ARGS_JSON

Example:

args: text: default: "" steps: - id: safe env: TEXT: "$LOBSTER_ARG_TEXT" command: |  jq -n --arg text "$TEXT" '{"result": $text}'