Open-source project Lobster provides a typed, local-first workflow shell designed to act as a "macro engine" for AI agents like OpenClaw. It transforms tools and skills into composable pipelines and automations, enabling AI agents to invoke complex workflows in a single step. This approach significantly saves AI token usage, enhances determinism, and improves the resumability of automated tasks, making it ideal for developers integrating AI into complex operational pipelines.

How It Works

Lobster utilizes a JSON-first approach for defining typed pipelines, jobs, and approval gates, moving beyond traditional text-based shell pipes. Its core design emphasizes local-first execution, ensuring workflows run reliably without external dependencies beyond the defined tools. A key advantage is its composability, allowing complex sequences of operations to be packaged as macros callable by AI agents. Lobster avoids introducing new authentication surfaces, leveraging existing mechanisms for token management.

Quick Start & Requirements

• Installation: Requires Node.js and pnpm. Install dependencies via pnpm install.
• Execution: Run commands using node ./bin/lobster.js <command>. Core commands include exec (for OS commands), approve (for gating), and run (for workflow files).
• Workflow Files: Supports YAML/JSON workflow definitions with steps, environment variables, conditions, and approval gates.
• OpenClaw Integration: Installs shim executables (openclaw.invoke, clawd.invoke) to call Lobster pipelines from workflows, requiring OPENCLAW_URL and optionally OPENCLAW_TOKEN environment variables.
• Documentation: Usage examples and command details are provided within the README.

Highlighted Details

• Typed Pipelines: Employs JSON-first typing for robust pipeline definitions.
• Local-First Execution: Ensures reliable operation without external service dependencies.
• Composable Macros: Enables AI agents to invoke complex, pre-defined workflows efficiently.
• Approval Gates: Supports interactive TTY prompts or --emit flags for programmatic approval integration.
• Safe Argument Handling: Prefers environment variables (LOBSTER_ARG_<NAME>, LOBSTER_ARGS_JSON) for passing complex or sensitive arguments to shell commands, mitigating injection risks.
• Data Flow: Facilitates seamless data passing between steps using stdin: $stepId.stdout.

Maintenance & Community

No specific details regarding maintainers, community channels (like Discord/Slack), or project roadmap were present in the provided README content.

Licensing & Compatibility

The license type and any compatibility notes for commercial use or closed-source linking were not explicitly stated in the provided README content.

Limitations & Caveats

Workflow steps execute commands within /bin/sh, requiring that invoked tools be actual executables or shell scripts. While interactive approval gates are supported via TTY prompts, programmatic integration relies on the --emit flag. The README does not detail support for platforms other than those compatible with Node.js and pnpm.