lobster

# Lobster

> **Contribute:** Source code & PRs welcome at [github.com/guwidoe/lobster-skill](https://github.com/guwidoe/lobster-skill)

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

## CLI Location

```bash
# 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

```bash
# 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

```bash
# 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:

```json
{
  "status": "needs_approva...