clawdbot/docs/tools/lobster.md

title, description

title	description
Lobster	Run Lobster pipelines (typed workflows) as a first-class Clawdbot tool.

Lobster

The lobster tool lets Clawdbot run Lobster pipelines as a local-first, typed workflow runtime.

This is designed for:

• Deterministic orchestration (move multi-step tool workflows out of the LLM)
• Human-in-the-loop approvals that halt and resume
• Lower token usage (one lobster.run call instead of many tool calls)

Security model

• Lobster runs as a local subprocess.
• Lobster does not manage OAuth or secrets.
• Side effects still go through Clawdbot tools (messaging, files, etc.).

Recommendations:

• Prefer configuring lobsterPath as an absolute path to avoid PATH hijack.
• Use Lobster approvals (approve) for any side-effectful step.

Actions

run

Run a pipeline in tool mode.

Example:

{
  "action": "run",
  "pipeline": "exec --json \"echo [1]\" | approve --prompt 'ok?'",
  "lobsterPath": "/absolute/path/to/lobster",
  "timeoutMs": 20000
}

resume

Resume a halted pipeline.

Example:

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true,
  "lobsterPath": "/absolute/path/to/lobster"
}

Output

Lobster returns a JSON envelope:

• ok: boolean
• status: ok | needs_approval | cancelled
• output: array of items
• requiresApproval: approval request object (when status=needs_approval)