{
  "title": "Lobster",
  "content": "Lobster is a workflow shell that lets OpenClaw run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.\n\nYour assistant can build the tools that manage itself. Ask for a workflow, and 30 minutes later you have a CLI plus pipelines that run as one call. Lobster is the missing piece: deterministic pipelines, explicit approvals, and resumable state.\n\nToday, complex workflows require many back-and-forth tool calls. Each call costs tokens, and the LLM has to orchestrate every step. Lobster moves that orchestration into a typed runtime:\n\n* **One call instead of many**: OpenClaw runs one Lobster tool call and gets a structured result.\n* **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.\n* **Resumable**: Halted workflows return a token; approve and resume without re-running everything.\n\n## Why a DSL instead of plain programs?\n\nLobster is intentionally small. The goal is not \"a new language,\" it's a predictable, AI-friendly pipeline spec with first-class approvals and resume tokens.\n\n* **Approve/resume is built in**: A normal program can prompt a human, but it can’t *pause and resume* with a durable token without you inventing that runtime yourself.\n* **Determinism + auditability**: Pipelines are data, so they’re easy to log, diff, replay, and review.\n* **Constrained surface for AI**: A tiny grammar + JSON piping reduces “creative” code paths and makes validation realistic.\n* **Safety policy baked in**: Timeouts, output caps, sandbox checks, and allowlists are enforced by the runtime, not each script.\n* **Still programmable**: Each step can call any CLI or script. If you want JS/TS, generate `.lobster` files from code.\n\nOpenClaw launches the local `lobster` CLI in **tool mode** and parses a JSON envelope from stdout.\nIf the pipeline pauses for approval, the tool returns a `resumeToken` so you can continue later.\n\n## Pattern: small CLI + JSON pipes + approvals\n\nBuild tiny commands that speak JSON, then chain them into a single Lobster call. (Example command names below — swap in your own.)\n\nIf the pipeline requests approval, resume with the token:\n\nAI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable.\n\nExample: map input items into tool calls:\n\n## JSON-only LLM steps (llm-task)\n\nFor workflows that need a **structured LLM step**, enable the optional\n`llm-task` plugin tool and call it from Lobster. This keeps the workflow\ndeterministic while still letting you classify/summarize/draft with a model.\n\nUse it in a pipeline:\n\nSee [LLM Task](/tools/llm-task) for details and configuration options.\n\n## Workflow files (.lobster)\n\nLobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In OpenClaw tool calls, set `pipeline` to the file path.\n\n* `stdin: $step.stdout` and `stdin: $step.json` pass a prior step’s output.\n* `condition` (or `when`) can gate steps on `$step.approved`.\n\nInstall the Lobster CLI on the **same host** that runs the OpenClaw Gateway (see the [Lobster repo](https://github.com/openclaw/lobster)), and ensure `lobster` is on `PATH`.\nIf you want to use a custom binary location, pass an **absolute** `lobsterPath` in the tool call.\n\nLobster is an **optional** plugin tool (not enabled by default).\n\nRecommended (additive, safe):\n\nAvoid using `tools.allow: [\"lobster\"]` unless you intend to run in restrictive allowlist mode.\n\nNote: allowlists are opt-in for optional plugins. If your allowlist only names\nplugin tools (like `lobster`), OpenClaw keeps core tools enabled. To restrict core\ntools, include the core tools or groups you want in the allowlist too.\n\n## Example: Email triage\n\nReturns a JSON envelope (truncated):\n\nUser approves → resume:\n\nOne workflow. Deterministic. Safe.\n\nRun a pipeline in tool mode.\n\nRun a workflow file with args:\n\nContinue a halted workflow after approval.\n\n* `lobsterPath`: Absolute path to the Lobster binary (omit to use `PATH`).\n* `cwd`: Working directory for the pipeline (defaults to the current process working directory).\n* `timeoutMs`: Kill the subprocess if it exceeds this duration (default: 20000).\n* `maxStdoutBytes`: Kill the subprocess if stdout exceeds this size (default: 512000).\n* `argsJson`: JSON string passed to `lobster run --args-json` (workflow files only).\n\nLobster returns a JSON envelope with one of three statuses:\n\n* `ok` → finished successfully\n* `needs_approval` → paused; `requiresApproval.resumeToken` is required to resume\n* `cancelled` → explicitly denied or cancelled\n\nThe tool surfaces the envelope in both `content` (pretty JSON) and `details` (raw object).\n\nIf `requiresApproval` is present, inspect the prompt and decide:\n\n* `approve: true` → resume and continue side effects\n* `approve: false` → cancel and finalize the workflow\n\nUse `approve --preview-from-stdin --limit N` to attach a JSON preview to approval requests without custom jq/heredoc glue. Resume tokens are now compact: Lobster stores workflow resume state under its state dir and hands back a small token key.\n\nOpenProse pairs well with Lobster: use `/prose` to orchestrate multi-agent prep, then run a Lobster pipeline for deterministic approvals. If a Prose program needs Lobster, allow the `lobster` tool for sub-agents via `tools.subagents.tools`. See [OpenProse](/prose).\n\n* **Local subprocess only** — no network calls from the plugin itself.\n* **No secrets** — Lobster doesn't manage OAuth; it calls OpenClaw tools that do.\n* **Sandbox-aware** — disabled when the tool context is sandboxed.\n* **Hardened** — `lobsterPath` must be absolute if specified; timeouts and output caps enforced.\n\n* **`lobster subprocess timed out`** → increase `timeoutMs`, or split a long pipeline.\n* **`lobster output exceeded maxStdoutBytes`** → raise `maxStdoutBytes` or reduce output size.\n* **`lobster returned invalid JSON`** → ensure the pipeline runs in tool mode and prints only JSON.\n* **`lobster failed (code …)`** → run the same pipeline in a terminal to inspect stderr.\n\n* [Plugins](/plugin)\n* [Plugin tool authoring](/plugins/agent-tools)\n\n## Case study: community workflows\n\nOne public example: a “second brain” CLI + Lobster pipelines that manage three Markdown vaults (personal, partner, shared). The CLI emits JSON for stats, inbox listings, and stale scans; Lobster chains those commands into workflows like `weekly-review`, `inbox-triage`, `memory-consolidation`, and `shared-task-sync`, each with approval gates. AI handles judgment (categorization) when available and falls back to deterministic rules when not.\n\n* Thread: [https://x.com/plattenschieber/status/2014508656335770033](https://x.com/plattenschieber/status/2014508656335770033)\n* Repo: [https://github.com/bloomedai/brain-cli](https://github.com/bloomedai/brain-cli)",
  "code_samples": [
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "If the pipeline requests approval, resume with the token:",
      "language": "unknown"
    },
    {
      "code": "AI triggers the workflow; Lobster executes the steps. Approval gates keep side effects explicit and auditable.\n\nExample: map input items into tool calls:",
      "language": "unknown"
    },
    {
      "code": "## JSON-only LLM steps (llm-task)\n\nFor workflows that need a **structured LLM step**, enable the optional\n`llm-task` plugin tool and call it from Lobster. This keeps the workflow\ndeterministic while still letting you classify/summarize/draft with a model.\n\nEnable the tool:",
      "language": "unknown"
    },
    {
      "code": "Use it in a pipeline:",
      "language": "unknown"
    },
    {
      "code": "See [LLM Task](/tools/llm-task) for details and configuration options.\n\n## Workflow files (.lobster)\n\nLobster can run YAML/JSON workflow files with `name`, `args`, `steps`, `env`, `condition`, and `approval` fields. In OpenClaw tool calls, set `pipeline` to the file path.",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* `stdin: $step.stdout` and `stdin: $step.json` pass a prior step’s output.\n* `condition` (or `when`) can gate steps on `$step.approved`.\n\n## Install Lobster\n\nInstall the Lobster CLI on the **same host** that runs the OpenClaw Gateway (see the [Lobster repo](https://github.com/openclaw/lobster)), and ensure `lobster` is on `PATH`.\nIf you want to use a custom binary location, pass an **absolute** `lobsterPath` in the tool call.\n\n## Enable the tool\n\nLobster is an **optional** plugin tool (not enabled by default).\n\nRecommended (additive, safe):",
      "language": "unknown"
    },
    {
      "code": "Or per-agent:",
      "language": "unknown"
    },
    {
      "code": "Avoid using `tools.allow: [\"lobster\"]` unless you intend to run in restrictive allowlist mode.\n\nNote: allowlists are opt-in for optional plugins. If your allowlist only names\nplugin tools (like `lobster`), OpenClaw keeps core tools enabled. To restrict core\ntools, include the core tools or groups you want in the allowlist too.\n\n## Example: Email triage\n\nWithout Lobster:",
      "language": "unknown"
    },
    {
      "code": "With Lobster:",
      "language": "unknown"
    },
    {
      "code": "Returns a JSON envelope (truncated):",
      "language": "unknown"
    },
    {
      "code": "User approves → resume:",
      "language": "unknown"
    },
    {
      "code": "One workflow. Deterministic. Safe.\n\n## Tool parameters\n\n### `run`\n\nRun a pipeline in tool mode.",
      "language": "unknown"
    },
    {
      "code": "Run a workflow file with args:",
      "language": "unknown"
    },
    {
      "code": "### `resume`\n\nContinue a halted workflow after approval.",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Hook",
      "id": "hook"
    },
    {
      "level": "h2",
      "text": "Why",
      "id": "why"
    },
    {
      "level": "h2",
      "text": "Why a DSL instead of plain programs?",
      "id": "why-a-dsl-instead-of-plain-programs?"
    },
    {
      "level": "h2",
      "text": "How it works",
      "id": "how-it-works"
    },
    {
      "level": "h2",
      "text": "Pattern: small CLI + JSON pipes + approvals",
      "id": "pattern:-small-cli-+-json-pipes-+-approvals"
    },
    {
      "level": "h2",
      "text": "JSON-only LLM steps (llm-task)",
      "id": "json-only-llm-steps-(llm-task)"
    },
    {
      "level": "h2",
      "text": "Workflow files (.lobster)",
      "id": "workflow-files-(.lobster)"
    },
    {
      "level": "h2",
      "text": "Install Lobster",
      "id": "install-lobster"
    },
    {
      "level": "h2",
      "text": "Enable the tool",
      "id": "enable-the-tool"
    },
    {
      "level": "h2",
      "text": "Example: Email triage",
      "id": "example:-email-triage"
    },
    {
      "level": "h2",
      "text": "Tool parameters",
      "id": "tool-parameters"
    },
    {
      "level": "h3",
      "text": "`run`",
      "id": "`run`"
    },
    {
      "level": "h3",
      "text": "`resume`",
      "id": "`resume`"
    },
    {
      "level": "h3",
      "text": "Optional inputs",
      "id": "optional-inputs"
    },
    {
      "level": "h2",
      "text": "Output envelope",
      "id": "output-envelope"
    },
    {
      "level": "h2",
      "text": "Approvals",
      "id": "approvals"
    },
    {
      "level": "h2",
      "text": "OpenProse",
      "id": "openprose"
    },
    {
      "level": "h2",
      "text": "Safety",
      "id": "safety"
    },
    {
      "level": "h2",
      "text": "Troubleshooting",
      "id": "troubleshooting"
    },
    {
      "level": "h2",
      "text": "Learn more",
      "id": "learn-more"
    },
    {
      "level": "h2",
      "text": "Case study: community workflows",
      "id": "case-study:-community-workflows"
    }
  ],
  "url": "llms-txt#lobster",
  "links": []
}