lobster

✓Verified·Scanned 2/18/2026

Lobster workflow runtime for deterministic pipelines with approval gates. Use when: (1) Running multi-step automations that need human approval before side effects, (2) Monitoring PRs/issues for changes, (3) Processing data through typed JSON pipelines, (4) Email triage or batch operations, (5) Any workflow that should halt and ask before acting. Lobster saves tokens by running deterministic pipelines instead of re-planning each step.

from clawhub.ai·v9148399·4.0 KB·0 installs

Scanned from 1.0.1 at 9148399 · Transparency log ↗

$ vett add clawhub.ai/guwidoe/lobster

Lobster

Contribute: Source code & PRs welcome at github.com/guwidoe/lobster-skill

Workflow runtime for AI agents — typed pipelines with approval gates.

CLI Location

# Set alias (adjust path to your install location)
LOBSTER="node /home/molt/clawd/tools/lobster/bin/lobster.js"

# Or install globally: npm install -g @clawdbot/lobster
# Then use: lobster '<pipeline>'

Quick Reference

# Run pipeline (human mode - pretty output)
$LOBSTER '<pipeline>'

# Run pipeline (tool mode - JSON envelope for integration)
$LOBSTER run --mode tool '<pipeline>'

# Run workflow file
$LOBSTER run path/to/workflow.lobster

# Resume after approval
$LOBSTER resume --token "<token>" --approve yes|no

# List commands/workflows
$LOBSTER commands.list
$LOBSTER workflows.list

Core Commands

Command	Purpose
`exec --json --shell "cmd"`	Run shell, parse stdout as JSON
`where 'field=value'`	Filter objects
`pick field1,field2`	Project fields
`head --n 5`	Take first N items
`sort --key field --desc`	Sort items
`groupBy --key field`	Group by key
`dedupe --key field`	Remove duplicates
`map --wrap key`	Transform items
`template --text "{{field}}"`	Render templates
`approve --prompt "ok?"`	Halt for approval
`diff.last --key "mykey"`	Compare to last run (stateful)
`state.get key` / `state.set key`	Read/write persistent state
`json` / `table`	Render output

Built-in Workflows

# Monitor PR for changes (stateful - remembers last state)
$LOBSTER "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

# Monitor PR and emit message only on change
$LOBSTER "workflows.run --name github.pr.monitor.notify --args-json '{\"repo\":\"owner/repo\",\"pr\":123}'"

Approval Flow (Tool Mode)

When a pipeline hits approve, it returns:

{
  "status": "needs_approval",
  "requiresApproval": {
    "prompt": "Send 3 emails?",
    "items": [...],
    "resumeToken": "eyJ..."
  }
}

To continue:

$LOBSTER resume --token "eyJ..." --approve yes

Example Pipelines

# List recent PRs, filter merged, show as table
$LOBSTER 'exec --json --shell "gh pr list --repo owner/repo --json number,title,state --limit 20" | where "state=MERGED" | table'

# Get data, require approval, then process
$LOBSTER run --mode tool 'exec --json --shell "echo [{\"id\":1},{\"id\":2}]" | approve --prompt "Process these?" | pick id | json'

# Diff against last run (only emit on change)
$LOBSTER 'exec --json --shell "gh pr view 123 --repo o/r --json state,title" | diff.last --key "pr:o/r#123" | json'

Workflow Files (.lobster)

YAML/JSON files with steps, conditions, and approval gates:

name: pr-review-reminder
steps:
  - id: fetch
    command: gh pr list --repo ${repo} --json number,title,reviewDecision
  - id: filter
    command: jq '[.[] | select(.reviewDecision == "")]'
    stdin: $fetch.stdout
  - id: notify
    command: echo "PRs needing review:" && cat
    stdin: $filter.stdout
    approval: required

Run: $LOBSTER run workflow.lobster --args-json '{"repo":"owner/repo"}'

Clawdbot Integration

Lobster can call Clawdbot tools via clawd.invoke:

$LOBSTER 'clawd.invoke --tool message --action send --args-json "{\"target\":\"123\",\"message\":\"hello\"}"'

Requires CLAWD_URL and CLAWD_TOKEN environment variables.

State Directory

Lobster stores state in ~/.lobster/state/ by default. Override with LOBSTER_STATE_DIR.