diff --git a/docs/tools/lobster.md b/docs/tools/lobster.md index 2e803846f..daf04fd39 100644 --- a/docs/tools/lobster.md +++ b/docs/tools/lobster.md @@ -23,6 +23,16 @@ Today, complex workflows require many back-and-forth tool calls. Each call costs - **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. +## Why a DSL instead of plain programs? + +Lobster 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. + +- **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. +- **Determinism + auditability**: Pipelines are data, so they’re easy to log, diff, replay, and review. +- **Constrained surface for AI**: A tiny grammar + JSON piping reduces “creative” code paths and makes validation realistic. +- **Safety policy baked in**: Timeouts, output caps, sandbox checks, and allowlists are enforced by the runtime, not each script. +- **Still programmable**: Each step can call any CLI or script. If you want JS/TS, generate `.lobster` files from code. + ## How it works Clawdbot launches the local `lobster` CLI in **tool mode** and parses a JSON envelope from stdout.