110 lines
2.5 KiB
Markdown
110 lines
2.5 KiB
Markdown
---
|
|
title: Lobster
|
|
description: Typed workflow runtime for Clawdbot — composable pipelines with approval gates.
|
|
---
|
|
|
|
# Lobster
|
|
|
|
Lobster is a workflow shell that lets Clawdbot run multi-step tool sequences as a single, deterministic operation with explicit approval checkpoints.
|
|
|
|
## Why
|
|
|
|
Today, 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:
|
|
|
|
- **One call instead of many**: Clawdbot calls `lobster.run(...)` once and gets a structured result.
|
|
- **Approvals built in**: Side effects (send email, post comment) halt the workflow until explicitly approved.
|
|
- **Resumable**: Halted workflows return a token; approve and resume without re-running everything.
|
|
|
|
## Example: Email triage
|
|
|
|
Without Lobster:
|
|
```
|
|
User: "Check my email and draft replies"
|
|
→ clawd calls gmail.list
|
|
→ LLM summarizes
|
|
→ User: "draft replies to #2 and #5"
|
|
→ LLM drafts
|
|
→ User: "send #2"
|
|
→ clawd calls gmail.send
|
|
(repeat daily, no memory of what was triaged)
|
|
```
|
|
|
|
With Lobster:
|
|
```
|
|
clawd calls: lobster.run("email.triage --limit 20")
|
|
|
|
Returns:
|
|
{
|
|
"status": "needs_approval",
|
|
"output": {
|
|
"summary": "5 need replies, 2 need action",
|
|
"drafts": [...]
|
|
},
|
|
"requiresApproval": {
|
|
"prompt": "Send 2 draft replies?",
|
|
"resumeToken": "..."
|
|
}
|
|
}
|
|
|
|
User approves → clawd calls: lobster.resume(token, approve: true)
|
|
→ Emails sent
|
|
```
|
|
|
|
One workflow. Deterministic. Safe.
|
|
|
|
## Enable
|
|
|
|
Lobster is an **optional** plugin tool. Enable it in your agent config:
|
|
|
|
```json
|
|
{
|
|
"agents": {
|
|
"list": [{
|
|
"id": "main",
|
|
"tools": {
|
|
"allow": ["lobster"]
|
|
}
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
You also need the `lobster` CLI installed locally.
|
|
|
|
## Actions
|
|
|
|
### `run`
|
|
|
|
Execute a Lobster pipeline in tool mode.
|
|
|
|
```json
|
|
{
|
|
"action": "run",
|
|
"pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
|
|
"timeoutMs": 30000
|
|
}
|
|
```
|
|
|
|
### `resume`
|
|
|
|
Continue a halted workflow after approval.
|
|
|
|
```json
|
|
{
|
|
"action": "resume",
|
|
"token": "<resumeToken>",
|
|
"approve": true
|
|
}
|
|
```
|
|
|
|
## Security
|
|
|
|
- **Local subprocess only** — no network calls from the plugin itself.
|
|
- **No secrets** — Lobster doesn't manage OAuth; it calls clawd tools that do.
|
|
- **Sandbox-aware** — disabled when `ctx.sandboxed` is true.
|
|
- **Hardened** — `lobsterPath` must be absolute if specified; timeouts and output caps enforced.
|
|
|
|
## Learn more
|
|
|
|
- [Lobster repo](https://github.com/vignesh07/lobster) — runtime, commands, and workflow examples.
|