Lobster

Lobster executes multi-step workflows with approval checkpoints. Use it when:

User wants a repeatable automation (triage, monitor, sync)
Actions need human approval before executing (send, post, delete)
Multiple tool calls should run as one deterministic operation

When to use Lobster

User intent	Use Lobster?
"Triage my email"	Yes — multi-step, may send replies
"Send a message"	No — single action, use message tool directly
"Check my email every morning and ask before replying"	Yes — scheduled workflow with approval
"What's the weather?"	No — simple query
"Monitor this PR and notify me of changes"	Yes — stateful, recurring

Basic usage

Run a pipeline

{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
}

Returns structured result:

{
  "protocolVersion": 1,
  "ok": true,
  "status": "ok",
  "output": [{ "summary": {...}, "items": [...] }],
  "requiresApproval": null
}

Handle approval

If the workflow needs approval:

{
  "status": "needs_approval",
  "output": [],
  "requiresApproval": {
    "prompt": "Send 3 draft replies?",
    "items": [...],
    "resumeToken": "..."
  }
}

Present the prompt to the user. If they approve:

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

Example workflows

Email triage

gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage

Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).

Email triage with approval gate

gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'

Same as above, but halts for approval before returning.

Key behaviors

Deterministic: Same input → same output (no LLM variance in pipeline execution)
Approval gates: approve command halts execution, returns token
Resumable: Use resume action with token to continue
Structured output: Always returns JSON envelope with protocolVersion

Don't use Lobster for

Simple single-action requests (just use the tool directly)
Queries that need LLM interpretation mid-flow
One-off tasks that won't be repeated

2.2 KiB Raw Blame History