{"id":44494294,"url":"https://github.com/openclaw/lobster","last_synced_at":"2026-04-06T15:03:56.452Z","repository":{"id":333226770,"uuid":"1136611506","full_name":"openclaw/lobster","owner":"openclaw","description":"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.","archived":false,"fork":false,"pushed_at":"2026-03-16T08:04:29.000Z","size":185,"stargazers_count":1044,"open_issues_count":31,"forks_count":237,"subscribers_count":20,"default_branch":"main","last_synced_at":"2026-04-03T03:23:48.145Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.openclaw.ai/tools/lobster","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openclaw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["moltbot"]}},"created_at":"2026-01-18T02:13:48.000Z","updated_at":"2026-04-03T03:16:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openclaw/lobster","commit_stats":null,"previous_names":["vignesh07/lobster","clawdbot/lobster","moltbot/lobster","openclaw/lobster"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/openclaw/lobster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Flobster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Flobster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Flobster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Flobster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openclaw","download_url":"https://codeload.github.com/openclaw/lobster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Flobster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31477014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-13T05:00:20.134Z","updated_at":"2026-04-06T15:03:56.447Z","avatar_url":"https://github.com/openclaw.png","language":"TypeScript","funding_links":["https://github.com/sponsors/moltbot"],"categories":["Skills \u0026 Plugins","🏛️ Official Resources","TypeScript","Entwicklertools und Observability","Official Resources","🦞 OpenClaw Ecosystem","Official"],"sub_categories":["Lobster Workflow Runtime","Other Cloud Provider Credits"],"readme":"# Lobster\n\nAn OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.\n\n\n## Example of Lobster at work\nOpenClaw (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.\n\n### Watching a PR that hasn't had changes\n```\nnode bin/lobster.js \"workflows.run --name github.pr.monitor --args-json '{\\\"repo\\\":\\\"openclaw/openclaw\\\",\\\"pr\\\":1152}'\"\n[\n  {\n    \"kind\": \"github.pr.monitor\",\n    \"repo\": \"openclaw/openclaw\",\n    \"prNumber\": 1152,\n    \"key\": \"github.pr:openclaw/openclaw#1152\",\n    \"changed\": false,\n    \"summary\": {\n      \"changedFields\": [],\n      \"changes\": {}\n    },\n    \"prSnapshot\": {\n      \"author\": {\n        \"id\": \"MDQ6VXNlcjE0MzY4NTM=\",\n        \"is_bot\": false,\n        \"login\": \"vignesh07\",\n        \"name\": \"Vignesh\"\n      },\n      \"baseRefName\": \"main\",\n      \"headRefName\": \"feat/lobster-plugin\",\n      \"isDraft\": false,\n      \"mergeable\": \"MERGEABLE\",\n      \"number\": 1152,\n      \"reviewDecision\": \"\",\n      \"state\": \"OPEN\",\n      \"title\": \"feat: Add optional lobster plugin tool (typed workflows, approvals/resume)\",\n      \"updatedAt\": \"2026-01-18T20:16:56Z\",\n      \"url\": \"https://github.com/openclaw/openclaw/pull/1152\"\n    }\n  }\n]\n```\n### And a PR that has a state change (in this case an approved PR)\n\n```\n node bin/lobster.js \"workflows.run --name github.pr.monitor --args-json '{\\\"repo\\\":\\\"openclaw/openclaw\\\",\\\"pr\\\":1200}'\"\n[\n  {\n    \"kind\": \"github.pr.monitor\",\n    \"repo\": \"openclaw/openclaw\",\n    \"prNumber\": 1200,\n    \"key\": \"github.pr:openclaw/openclaw#1200\",\n    \"changed\": true,\n    \"summary\": {\n      \"changedFields\": [\n        \"number\",\n        \"title\",\n        \"url\",\n        \"state\",\n        \"isDraft\",\n        \"mergeable\",\n        \"reviewDecision\",\n        \"updatedAt\",\n        \"baseRefName\",\n        \"headRefName\"\n      ],\n      \"changes\": {\n        \"number\": {\n          \"from\": null,\n          \"to\": 1200\n        },\n        \"title\": {\n          \"from\": null,\n          \"to\": \"feat(tui): add syntax highlighting for code blocks\"\n        },\n        \"url\": {\n          \"from\": null,\n          \"to\": \"https://github.com/openclaw/openclaw/pull/1200\"\n        },\n        \"state\": {\n          \"from\": null,\n          \"to\": \"MERGED\"\n        },\n        \"isDraft\": {\n          \"from\": null,\n          \"to\": false\n        },\n        \"mergeable\": {\n          \"from\": null,\n          \"to\": \"UNKNOWN\"\n        },\n        \"reviewDecision\": {\n          \"from\": null,\n          \"to\": \"\"\n        },\n        \"updatedAt\": {\n          \"from\": null,\n          \"to\": \"2026-01-19T05:06:09Z\"\n        },\n        \"baseRefName\": {\n          \"from\": null,\n          \"to\": \"main\"\n        },\n        \"headRefName\": {\n          \"from\": null,\n          \"to\": \"feat/tui-syntax-highlighting\"\n        }\n      }\n    },\n    \"prSnapshot\": {\n      \"author\": {\n        \"id\": \"MDQ6VXNlcjE0MzY4NTM=\",\n        \"is_bot\": false,\n        \"login\": \"vignesh07\",\n        \"name\": \"Vignesh\"\n      },\n      \"baseRefName\": \"main\",\n      \"headRefName\": \"feat/tui-syntax-highlighting\",\n      \"isDraft\": false,\n      \"mergeable\": \"UNKNOWN\",\n      \"number\": 1200,\n      \"reviewDecision\": \"\",\n      \"state\": \"MERGED\",\n      \"title\": \"feat(tui): add syntax highlighting for code blocks\",\n      \"updatedAt\": \"2026-01-19T05:06:09Z\",\n      \"url\": \"https://github.com/openclaw/openclaw/pull/1200\"\n    }\n  }\n]\n```\n\n## Goals\n\n\n- Typed pipelines (objects/arrays), not text pipes.\n- Local-first execution.\n- No new auth surface: Lobster must not own OAuth/tokens.\n- Composable macros that OpenClaw (or any agent) can invoke in one step to save tokens.\n\n## Quick start\n\nFrom this folder:\n\n- `pnpm install`\n- `pnpm test`\n- `pnpm lint`\n- `node ./bin/lobster.js --help`\n- `node ./bin/lobster.js doctor`\n- `node ./bin/lobster.js \"exec --json --shell 'echo [1,2,3]' | where '0\u003e=0' | json\"`\n\n### Notes\n\n- `pnpm test` runs `tsc` and then executes tests against `dist/`.\n- `bin/lobster.js` prefers the compiled entrypoint in `dist/` when present.\n## Commands\n\n- `exec`: run OS commands\n- `exec --stdin raw|json|jsonl`: feed pipeline input into subprocess stdin\n- `where`, `pick`, `head`: data shaping\n- `json`, `table`: renderers\n- `approve`: approval gate (TTY prompt or `--emit` for OpenClaw integration)\n\n## Next steps\n\n- OpenClaw integration: ship as an optional OpenClaw plugin tool.\n\n## Workflow files\n\nLobster workflow files are meant to read like small scripts:\n\n- `run:` or `command:` for deterministic shell/CLI steps\n- `pipeline:` for native Lobster stages like `llm.invoke`\n- `approval:` for hard workflow gates between steps\n- `stdin: $step.stdout` or `stdin: $step.json` to pass data forward\n\n```\nlobster run path/to/workflow.lobster\nlobster run --file path/to/workflow.lobster --args-json '{\"tag\":\"family\"}'\n```\n\nExample file:\n\n```yaml\nname: jacket-advice\nargs:\n  location:\n    default: Phoenix\nsteps:\n  - id: fetch\n    run: weather --json ${location}\n\n  - id: confirm\n    approval: Want jacket advice from the LLM?\n    stdin: $fetch.json\n\n  - id: advice\n    pipeline: \u003e\n      llm.invoke --prompt \"Given this weather data, should I wear a jacket?\n      Be concise and return JSON.\"\n    stdin: $fetch.json\n    when: $confirm.approved\n```\n\nNotes:\n\n- `run:` and `command:` are equivalent; `run:` is the preferred spelling for new files.\n- `pipeline:` shares the same args/env/results model as shell steps, so later steps can still reference `$step.stdout` or `$step.json`.\n- 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.\n- `cwd`, `env`, `stdin`, `when`, and `condition` work for both shell and pipeline steps.\n\n## Calling LLMs from workflows\n\nUse `llm.invoke` from a native `pipeline:` step for model-backed work:\n\n```bash\nllm.invoke --prompt 'Summarize this diff'\nllm.invoke --provider openclaw --prompt 'Summarize this diff'\nllm.invoke --provider pi --prompt 'Summarize this diff'\n```\n\nProvider resolution order:\n\n- `--provider`\n- `LOBSTER_LLM_PROVIDER`\n- auto-detect from environment\n\nBuilt-in providers today:\n\n- `openclaw` via `OPENCLAW_URL` / `OPENCLAW_TOKEN`\n- `pi` via `LOBSTER_PI_LLM_ADAPTER_URL` (typically supplied by the Pi extension)\n- `http` via `LOBSTER_LLM_ADAPTER_URL`\n\n`llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.\n\n## Calling OpenClaw tools from workflows\n\nShell `run:` steps execute in your system shell, so OpenClaw tool calls there must be real executables.\n\nIf you install Lobster via npm/pnpm, it installs a small shim executable named:\n\n- `openclaw.invoke` (preferred)\n- `clawd.invoke` (alias)\n\nThese shims forward to the Lobster pipeline command of the same name.\n\n### Example: invoke llm-task\n\nPrereqs:\n\n- `OPENCLAW_URL` points at a running OpenClaw gateway\n- optionally `OPENCLAW_TOKEN` if auth is enabled\n\n```bash\nexport OPENCLAW_URL=http://127.0.0.1:18789\n# export OPENCLAW_TOKEN=...\n```\n\nIn a workflow:\n\n```yaml\nname: hello-world\nsteps:\n  - id: greeting\n    run: \u003e\n      openclaw.invoke --tool llm-task --action json --args-json '{\"prompt\":\"Hello\"}'\n```\n\n### Passing data between steps (no temp files)\n\nUse `stdin: $stepId.stdout` to pipe output from one step into the next.\n\n## Args and shell-safety\n\n`${arg}` substitution is a raw string replace into the shell command text.\n\nFor anything that may contain quotes, `$`, backticks, or newlines, prefer env vars:\n\n- every resolved workflow arg is exposed as `LOBSTER_ARG_\u003cNAME\u003e` (uppercased, non-alnum → `_`)\n- the full args object is also available as `LOBSTER_ARGS_JSON`\n\nExample:\n\n```yaml\nargs:\n  text:\n    default: \"\"\nsteps:\n  - id: safe\n    env:\n      TEXT: \"$LOBSTER_ARG_TEXT\"\n    command: |\n      jq -n --arg text \"$TEXT\" '{\"result\": $text}'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Flobster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenclaw%2Flobster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Flobster/lists"}