Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# Lobster

A Moltbot-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.
A OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.


## Example of lobster at work
Moltbot or any other AI agent can use `lobster` as a workflow engine and not construct a query every time - thus saving tokens, providing room for determinism, and resumability.
OpenClaw or any other AI agent can use `lobster` as a workflow engine and not construct a query every time - thus saving tokens, providing room for determinism, and resumability.

### Watching a PR that hasn't had changes
```
node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"moltbot/moltbot\",\"pr\":1152}'"
node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1152}'"
[
{
"kind": "github.pr.monitor",
"repo": "moltbot/moltbot",
"repo": "openclaw/openclaw",
"prNumber": 1152,
"key": "github.pr:moltbot/moltbot#1152",
"key": "github.pr:openclaw/openclaw#1152",
"changed": false,
"summary": {
"changedFields": [],
Expand All @@ -36,21 +36,21 @@ node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo
"state": "OPEN",
"title": "feat: Add optional lobster plugin tool (typed workflows, approvals/resume)",
"updatedAt": "2026-01-18T20:16:56Z",
"url": "https://github.com/moltbot/moltbot/pull/1152"
"url": "https://github.com/openclaw/openclaw/pull/1152"
}
}
]
```
### And a PR that has a state change (in this case an approved PR)

```
node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"moltbot/moltbot\",\"pr\":1200}'"
node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1200}'"
[
{
"kind": "github.pr.monitor",
"repo": "moltbot/moltbot",
"repo": "openclaw/openclaw",
"prNumber": 1200,
"key": "github.pr:moltbot/moltbot#1200",
"key": "github.pr:openclaw/openclaw#1200",
"changed": true,
"summary": {
"changedFields": [
Expand All @@ -76,7 +76,7 @@ node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo
},
"url": {
"from": null,
"to": "https://github.com/moltbot/moltbot/pull/1200"
"to": "https://github.com/openclaw/openclaw/pull/1200"
},
"state": {
"from": null,
Expand Down Expand Up @@ -124,7 +124,7 @@ node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo
"state": "MERGED",
"title": "feat(tui): add syntax highlighting for code blocks",
"updatedAt": "2026-01-19T05:06:09Z",
"url": "https://github.com/moltbot/moltbot/pull/1200"
"url": "https://github.com/openclaw/openclaw/pull/1200"
}
}
]
Expand All @@ -136,7 +136,7 @@ node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo
- Typed pipelines (objects/arrays), not text pipes.
- Local-first execution.
- No new auth surface: Lobster must not own OAuth/tokens.
- Composable macros that Moltbot can invoke in one step to save tokens.
- Composable macros that OpenClaw can invoke in one step to save tokens.

## Quick start

Expand All @@ -159,11 +159,11 @@ From this folder:
- `exec --stdin raw|json|jsonl`: feed pipeline input into subprocess stdin
- `where`, `pick`, `head`: data shaping
- `json`, `table`: renderers
- `approve`: approval gate (TTY prompt or `--emit` for Moltbot integration)
- `approve`: approval gate (TTY prompt or `--emit` for OpenClaw integration)

## Next steps

- Moltbot integration: ship as an optional Moltbot plugin tool.
- OpenClaw integration: ship as an optional OpenClaw plugin tool.

## Workflow files

Expand Down
46 changes: 23 additions & 23 deletions VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,26 @@

## One-liner

**Lobster is safe automation for Clawdbot — workflows that ask before acting.**
**Lobster is safe automation for OpenClaw — workflows that ask before acting.**

---

## What is Lobster?

Lobster is a workflow runtime for Clawdbot. It lets you define multi-step automations that:
Lobster is a workflow runtime for OpenClaw. It lets you define multi-step automations that:

- Run deterministically (no LLM re-planning each step)
- Halt at checkpoints and ask for approval before side effects
- Resume exactly where they left off
- Remember what they've already processed

Think of it as **IFTTT/Zapier for Clawdbot, but with human checkpoints**.
Think of it as **IFTTT/Zapier for OpenClaw, but with human checkpoints**.

---

## The Problem Lobster Solves

### Today's workflow in Clawdbot
### Today's workflow in OpenClaw

```
User: "Check my email, draft replies to anything urgent, and send them"
Expand All @@ -46,7 +46,7 @@ What happens:
### With Lobster

```
Clawdbot calls: lobster.run("email.triage")
OpenClaw calls: lobster.run("email.triage")

What happens:
1. Lobster fetches emails (deterministic)
Expand All @@ -63,7 +63,7 @@ Tomorrow: Lobster remembers cursor, only processes new emails

---

## Why Lobster Makes Clawdbot Better
## Why Lobster Makes OpenClaw Better

| Without Lobster | With Lobster |
|-----------------|--------------|
Expand All @@ -85,7 +85,7 @@ Workflows can persist state: "last processed email ID", "last PR SHA seen", etc.

---

## How Lobster Fits with Clawdbot
## How Lobster Fits with OpenClaw

```
┌─────────────────────────────────────────────────┐
Expand All @@ -95,7 +95,7 @@ Workflows can persist state: "last processed email ID", "last PR SHA seen", etc.
┌─────────────────────────────────────────────────┐
Clawdbot
OpenClaw
│ - Understands intent │
│ - Chooses appropriate tool/workflow │
│ - Presents results and approval prompts │
Expand All @@ -105,23 +105,23 @@ Workflows can persist state: "last processed email ID", "last PR SHA seen", etc.
┌─────────────────────────────────────────────────┐
│ Lobster │
│ - Executes deterministic pipeline │
│ - Calls Clawdbot tools (gmail, trello, etc) │
│ - Calls OpenClaw tools (gmail, trello, etc) │
│ - Halts at approval checkpoints │
│ - Returns structured result + resume token │
└─────────────────────────────────────────────────┘
```

**Key insight:** Lobster doesn't replace Clawdbot. It's the execution layer that makes Clawdbot's automations safe and efficient.
**Key insight:** Lobster doesn't replace OpenClaw. It's the execution layer that makes OpenClaw's automations safe and efficient.

- **Clawdbot** = the brain (understands what you want)
- **OpenClaw** = the brain (understands what you want)
- **Lobster** = the hands (executes workflows safely)
- **Tools/Skills** = the capabilities (gmail, trello, github, etc.)

---

## Who Should Use Lobster?

### Average Clawdbot users (invisible benefit)
### Average OpenClaw users (invisible benefit)
They don't need to know Lobster exists. They just notice:
- "Set up daily email triage" works better
- Automations ask before sending/posting
Expand All @@ -133,7 +133,7 @@ They can:
- Write new workflows for their specific needs
- Share workflows with the community

### The Clawdbot ecosystem
### The OpenClaw ecosystem
- Workflow recipes become a new category of shareable assets
- Skills stay simple (just expose APIs)
- Lobster handles the orchestration layer
Expand All @@ -151,21 +151,21 @@ They can:
| Temporal | But 80/20 version for personal workflows |

**Best analogy for most people:**
> "Lobster is Zapier for Clawdbot, except it asks you before doing anything irreversible."
> "Lobster is Zapier for OpenClaw, except it asks you before doing anything irreversible."

---

## Why Not Build This Into Clawdbot Core?
## Why Not Build This Into OpenClaw Core?

It could be. But the plugin architecture is intentional:

1. **Core stays small** — Clawdbot is already complex
1. **Core stays small** — OpenClaw is already complex
2. **Faster iteration** — Lobster can evolve without core releases
3. **Opt-in** — Not everyone needs workflow automation
4. **Community** — Easier to contribute workflows than core changes
5. **Ecosystem proof** — If plugins work for Lobster, they work for other capabilities

Pete (Clawdbot creator) explicitly built the plugin boundary to enable this pattern. Lobster is the first proof that it works.
Pete (OpenClaw creator, formerly Clawdbot) explicitly built the plugin boundary to enable this pattern. Lobster is the first proof that it works.

---

Expand Down Expand Up @@ -221,9 +221,9 @@ Other automation tools either:
- Don't integrate with your AI assistant

Lobster is:
- Native to Clawdbot (uses the same tools you already have)
- Native to OpenClaw (uses the same tools you already have)
- Safe by default (approvals are a language primitive)
- Invisible when you want (Clawdbot uses it automatically)
- Invisible when you want (OpenClaw uses it automatically)
- Customizable when you need (write your own workflows)

---
Expand All @@ -232,18 +232,18 @@ Lobster is:

- **Not a terminal replacement** — You don't switch your shell to Lobster
- **Not a general programming language** — It's for workflows, not apps
- **Not trying to replace Clawdbot** — It makes Clawdbot better
- **Not managing your secrets** — Clawdbot handles auth, Lobster orchestrates
- **Not trying to replace OpenClaw** — It makes OpenClaw better
- **Not managing your secrets** — OpenClaw handles auth, Lobster orchestrates

---

## Summary

| Question | Answer |
|----------|--------|
| What is it? | Workflow runtime for Clawdbot |
| What is it? | Workflow runtime for OpenClaw |
| One-liner? | Safe automation — workflows that ask before acting |
| Why use it? | Cheaper, safer, stateful automations |
| Who uses it? | Everyone (invisibly) or power users (directly) |
| Why not in core? | Plugin architecture — core stays small, capabilities are extensions |
| Best analogy? | Zapier for Clawdbot, but with approval checkpoints |
| Best analogy? | Zapier for OpenClaw, but with approval checkpoints |
10 changes: 5 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"name": "@clawdbot/lobster",
"name": "@openclaw/lobster",
"version": "2026.1.21-1",
"description": "Workflow runtime for AI agents - deterministic pipelines with approval gates",
"type": "module",
Expand Down Expand Up @@ -43,16 +43,16 @@
"approval",
"pipeline",
"lobster",
"clawdbot"
"openclaw"
],
"repository": {
"type": "git",
"url": "git+https://github.com/clawdbot/lobster.git"
"url": "git+https://github.com/openclaw/lobster.git"
},
"bugs": {
"url": "https://github.com/clawdbot/lobster/issues"
"url": "https://github.com/openclaw/lobster/issues"
},
"homepage": "https://github.com/clawdbot/lobster#readme",
"homepage": "https://github.com/openclaw/lobster#readme",
"license": "MIT",
"dependencies": {
"ajv": "^8.17.1",
Expand Down
2 changes: 1 addition & 1 deletion src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -449,7 +449,7 @@ function writeToolEnvelope(payload) {
}

function helpText() {
return `lobster — Clawdbot-native typed shell\n\n` +
return `lobster — OpenClaw-native typed shell\n\n` +
`Usage:\n` +
` lobster '<pipeline>'\n` +
` lobster run --mode tool '<pipeline>'\n` +
Expand Down
2 changes: 1 addition & 1 deletion src/commands/commands_list.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ export const commandsListCommand: LobsterCommand = {
`Usage:\n` +
` commands.list\n\n` +
`Notes:\n` +
` - Intended for agents (e.g. Clawdbot) to discover available pipeline stages dynamically.\n` +
` - Intended for agents (e.g. OpenClaw) to discover available pipeline stages dynamically.\n` +
` - Output includes name/description plus optional metadata (argsSchema/examples/sideEffects) when provided by commands.\n`
);
},
Expand Down
6 changes: 3 additions & 3 deletions src/commands/stdlib/clawd_invoke.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
export const clawdInvokeCommand = {
name: 'clawd.invoke',
meta: {
description: 'Call a local Clawdbot tool endpoint',
description: 'Call a local OpenClaw tool endpoint',
argsSchema: {
type: 'object',
properties: {
url: { type: 'string', description: 'Clawdbot control URL (or CLAWD_URL)' },
url: { type: 'string', description: 'OpenClaw control URL (or CLAWD_URL)' },
token: { type: 'string', description: 'Bearer token (or CLAWD_TOKEN)' },
tool: { type: 'string', description: 'Tool name (e.g. message, cron, github, etc.)' },
action: { type: 'string', description: 'Tool action' },
Expand All @@ -21,7 +21,7 @@ export const clawdInvokeCommand = {
sideEffects: ['calls_clawd_tool'],
},
help() {
return `clawd.invoke — call a local Clawdbot tool endpoint\n\n` +
return `clawd.invoke — call a local OpenClaw tool endpoint\n\n` +
`Usage:\n` +
` clawd.invoke --tool message --action send --args-json '{"provider":"telegram","to":"...","message":"..."}'\n` +
` clawd.invoke --tool message --action send --args-json '{...}' --dry-run\n` +
Expand Down
2 changes: 1 addition & 1 deletion src/commands/stdlib/email_triage.ts
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@ export const emailTriageCommand = {
}

const model = String(args.model ?? '').trim();
// Model is optional when running under Clawdbot (llm_task.invoke will use Clawdbot defaults).
// Model is optional when running under OpenClaw (llm_task.invoke will use OpenClaw defaults).

if (!ctx?.registry) throw new Error('email.triage (LLM mode) requires ctx.registry');
const llmCmd = ctx.registry.get('llm_task.invoke');
Expand Down
Loading