https://github.com/openclaw/lobster

Lobster is a Openclaw-native workflow shell: a typed, local-first “macro engine” that turns skills/tools into composable pipelines and safe automations—and lets Openclaw call those workflows in one step.
https://github.com/openclaw/lobster

Last synced: 2 months ago
JSON representation

Lobster is a Openclaw-native workflow shell: a typed, local-first “macro engine” that turns skills/tools into composable pipelines and safe automations—and lets Openclaw call those workflows in one step.

• Host: GitHub
• URL: https://github.com/openclaw/lobster
• Owner: openclaw
• License: mit
• Created: 2026-01-18T02:13:48.000Z (5 months ago)
• Default Branch: main
• Last Pushed: 2026-03-16T08:04:29.000Z (3 months ago)
• Last Synced: 2026-04-03T03:23:48.145Z (2 months ago)
• Language: TypeScript
• Homepage: https://docs.openclaw.ai/tools/lobster
• Size: 181 KB
• Stars: 1,044
• Watchers: 20
• Forks: 237
• Open Issues: 31
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

• awesome-openclaw - openclaw/lobster - Official workflow shell for composing tools and resumable automations. (🏛️ Official Resources)
• awesome-ccamel - openclaw/lobster - Lobster is a Openclaw-native workflow shell: a typed, local-first “macro engine” that turns skills/tools into composable pipelines and safe automations—and lets Openclaw call those workflows in one step. (TypeScript)
• awesome-openclaw - openclaw/lobster - Workflow-Shell zum Kombinieren von OpenClaw-Tools und Automationen. 🎖️  (Entwicklertools und Observability)
• awesome-openclaw - Lobster - native workflow shell for composable pipelines | (Official Resources)
• awesome-ai-tools - openclaw/lobster - native workflow shell / macro engine (🦞 OpenClaw Ecosystem / Other Cloud Provider Credits)
• awesome-claw - openclaw/lobster - Lobster workflow shell — a typed, local-first macro engine for composable pipelines and safe automations (JavaScript) (Official)

README

          
# Lobster

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

## Example of Lobster at work

OpenClaw (or any other AI agent) can use `lobster` as a workflow engine and avoid re-planning every step — saving tokens while improving determinism and resumability.

### Watching a PR that hasn't had changes

```

node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1152}'"

[

  {

    "kind": "github.pr.monitor",

    "repo": "openclaw/openclaw",

    "prNumber": 1152,

    "key": "github.pr:openclaw/openclaw#1152",

    "changed": false,

    "summary": {

      "changedFields": [],

      "changes": {}

    },

    "prSnapshot": {

      "author": {

        "id": "MDQ6VXNlcjE0MzY4NTM=",

        "is_bot": false,

        "login": "vignesh07",

        "name": "Vignesh"

      },

      "baseRefName": "main",

      "headRefName": "feat/lobster-plugin",

      "isDraft": false,

      "mergeable": "MERGEABLE",

      "number": 1152,

      "reviewDecision": "",

      "state": "OPEN",

      "title": "feat: Add optional lobster plugin tool (typed workflows, approvals/resume)",

      "updatedAt": "2026-01-18T20:16:56Z",

      "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\":\"openclaw/openclaw\",\"pr\":1200}'"

[

  {

    "kind": "github.pr.monitor",

    "repo": "openclaw/openclaw",

    "prNumber": 1200,

    "key": "github.pr:openclaw/openclaw#1200",

    "changed": true,

    "summary": {

      "changedFields": [

        "number",

        "title",

        "url",

        "state",

        "isDraft",

        "mergeable",

        "reviewDecision",

        "updatedAt",

        "baseRefName",

        "headRefName"

      ],

      "changes": {

        "number": {

          "from": null,

          "to": 1200

        },

        "title": {

          "from": null,

          "to": "feat(tui): add syntax highlighting for code blocks"

        },

        "url": {

          "from": null,

          "to": "https://github.com/openclaw/openclaw/pull/1200"

        },

        "state": {

          "from": null,

          "to": "MERGED"

        },

        "isDraft": {

          "from": null,

          "to": false

        },

        "mergeable": {

          "from": null,

          "to": "UNKNOWN"

        },

        "reviewDecision": {

          "from": null,

          "to": ""

        },

        "updatedAt": {

          "from": null,

          "to": "2026-01-19T05:06:09Z"

        },

        "baseRefName": {

          "from": null,

          "to": "main"

        },

        "headRefName": {

          "from": null,

          "to": "feat/tui-syntax-highlighting"

        }

      }

    },

    "prSnapshot": {

      "author": {

        "id": "MDQ6VXNlcjE0MzY4NTM=",

        "is_bot": false,

        "login": "vignesh07",

        "name": "Vignesh"

      },

      "baseRefName": "main",

      "headRefName": "feat/tui-syntax-highlighting",

      "isDraft": false,

      "mergeable": "UNKNOWN",

      "number": 1200,

      "reviewDecision": "",

      "state": "MERGED",

      "title": "feat(tui): add syntax highlighting for code blocks",

      "updatedAt": "2026-01-19T05:06:09Z",

      "url": "https://github.com/openclaw/openclaw/pull/1200"

    }

  }

]

```

## Goals

- Typed pipelines (objects/arrays), not text pipes.

- Local-first execution.

- No new auth surface: Lobster must not own OAuth/tokens.

- Composable macros that OpenClaw (or any agent) can invoke in one step to save tokens.

## Quick start

From this folder:

- `pnpm install`

- `pnpm test`

- `pnpm lint`

- `node ./bin/lobster.js --help`

- `node ./bin/lobster.js doctor`

- `node ./bin/lobster.js "exec --json --shell 'echo [1,2,3]' | where '0>=0' | json"`

### Notes

- `pnpm test` runs `tsc` and then executes tests against `dist/`.

- `bin/lobster.js` prefers the compiled entrypoint in `dist/` when present.

## Commands

- `exec`: run OS commands

- `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 OpenClaw integration)

## Next steps

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

## Workflow files

Lobster workflow files are meant to read like small scripts:

- `run:` or `command:` for deterministic shell/CLI steps

- `pipeline:` for native Lobster stages like `llm.invoke`

- `approval:` for hard workflow gates between steps

- `stdin: $step.stdout` or `stdin: $step.json` to pass data forward

```

lobster run path/to/workflow.lobster

lobster run --file path/to/workflow.lobster --args-json '{"tag":"family"}'

```

Example file:

```yaml

name: jacket-advice

args:

  location:

    default: Phoenix

steps:

  - id: fetch

    run: weather --json ${location}

  - id: confirm

    approval: Want jacket advice from the LLM?

    stdin: $fetch.json

  - id: advice

    pipeline: >

      llm.invoke --prompt "Given this weather data, should I wear a jacket?

      Be concise and return JSON."

    stdin: $fetch.json

    when: $confirm.approved

```

Notes:

- `run:` and `command:` are equivalent; `run:` is the preferred spelling for new files.

- `pipeline:` shares the same args/env/results model as shell steps, so later steps can still reference `$step.stdout` or `$step.json`.

- If you need a human checkpoint before an LLM call, use a dedicated `approval:` step in the workflow file rather than `approve` inside the nested pipeline.

- `cwd`, `env`, `stdin`, `when`, and `condition` work for both shell and pipeline steps.

## Calling LLMs from workflows

Use `llm.invoke` from a native `pipeline:` step for model-backed work:

```bash

llm.invoke --prompt 'Summarize this diff'

llm.invoke --provider openclaw --prompt 'Summarize this diff'

llm.invoke --provider pi --prompt 'Summarize this diff'

```

Provider resolution order:

- `--provider`

- `LOBSTER_LLM_PROVIDER`

- auto-detect from environment

Built-in providers today:

- `openclaw` via `OPENCLAW_URL` / `OPENCLAW_TOKEN`

- `pi` via `LOBSTER_PI_LLM_ADAPTER_URL` (typically supplied by the Pi extension)

- `http` via `LOBSTER_LLM_ADAPTER_URL`

`llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.

## Calling OpenClaw tools from workflows

Shell `run:` steps execute in your system shell, so OpenClaw tool calls there must be real executables.

If you install Lobster via npm/pnpm, it installs a small shim executable named:

- `openclaw.invoke` (preferred)

- `clawd.invoke` (alias)

These shims forward to the Lobster pipeline command of the same name.

### Example: invoke llm-task

Prereqs:

- `OPENCLAW_URL` points at a running OpenClaw gateway

- optionally `OPENCLAW_TOKEN` if auth is enabled

```bash

export OPENCLAW_URL=http://127.0.0.1:18789

# export OPENCLAW_TOKEN=...

```

In a workflow:

```yaml

name: hello-world

steps:

  - id: greeting

    run: >

      openclaw.invoke --tool llm-task --action json --args-json '{"prompt":"Hello"}'

```

### Passing data between steps (no temp files)

Use `stdin: $stepId.stdout` to pipe output from one step into the next.

## Args and shell-safety

`${arg}` substitution is a raw string replace into the shell command text.

For anything that may contain quotes, `$`, backticks, or newlines, prefer env vars:

- every resolved workflow arg is exposed as `LOBSTER_ARG_` (uppercased, non-alnum → `_`)

- the full args object is also available as `LOBSTER_ARGS_JSON`

Example:

```yaml

args:

  text:

    default: ""

steps:

  - id: safe

    env:

      TEXT: "$LOBSTER_ARG_TEXT"

    command: |

      jq -n --arg text "$TEXT" '{"result": $text}'

```