Lobster — Workflow Shell

Typed, local-first pipeline engine. Deterministic execution, approval gates, persistent state. Saves tokens by replacing multi-step LLM re-planning with one-shot pipeline calls.

CLI

lobster '<pipeline>'                    # inline pipeline
lobster run path/to/workflow.lobster    # YAML workflow file
lobster run --file wf.lobster --args-json '{"key":"val"}'
lobster resume --token <token> --approve yes|no
lobster doctor                          # health check
lobster help <command>                  # per-command help

Pipeline Commands

Data flow

Output

Control flow

Integrations

Pipe syntax

Commands are piped with |. Data flows as typed JSON arrays (not text).

lobster "exec --json --shell 'gh pr list --json number,title,state' | where 'state=OPEN' | pick 'number,title' | head --n 5 | table"

Workflow files (.lobster)

YAML files with steps, env vars, conditions, and approval gates:

name: deploy-check
steps:
  - id: tests
    command: exec --json --shell 'pnpm test --json'
  - id: approve
    command: approve --prompt "Tests passed. Deploy to staging?"
    approval: required
  - id: deploy
    command: exec --shell 'pnpm deploy:staging'
    condition: $approve.approved

Run: lobster run deploy-check.lobster

Steps can reference prior outputs: stdin: $tests.stdout

Tool mode (for OpenClaw integration)

lobster run --mode tool '<pipeline>'

Returns a JSON envelope: { ok, status, output, requiresApproval }

When status: "needs_approval", call lobster resume --token <token> --approve yes to continue.

Built-in recipes

GitHub PR Monitor

lobster "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

Tracks PR state changes with diff detection.

State persistence

state.set / state.get persist JSON values across runs (e.g., last-processed cursor). diff.last compares current data to a stored snapshot and emits only changes.

Key principles

• One call — replace 10+ LLM tool calls with one pipeline
• Approval gates — hard stops, not prompt hints. Pipeline cannot continue without explicit resume.
• Stateful — cursors/checkpoints survive across runs
• No auth surface — Lobster never owns tokens; uses env vars or OpenClaw's existing auth