Lobster is an OpenClaw-native workflow shell designed to serve as a typed, local-first macro engine that transforms skills and tools into composable pipelines and safe automations. Built in TypeScript, it enables OpenClaw and other AI agents to invoke complex workflows in a single step, reducing token consumption and improving determinism and resumability compared to replanning every step. The project is classified across multiple domains including serverless computing, framework development, deployment tooling, function-as-a-service, multi-cloud support, extensibility, CLI tooling, application building, modularity, and lightweight architecture.
The core philosophy behind Lobster centers on several key design goals. It uses typed pipelines based on objects and arrays rather than text pipes, operates with local-first execution to avoid external dependencies, maintains a principle of not introducing new authentication surfaces by refusing to own OAuth tokens or credentials, and enables composable macros that agents can invoke in single steps to conserve computational resources. Workflow files are designed to read like small scripts, supporting deterministic shell and CLI steps via run or command directives, native Lobster pipeline stages, and approval gates that create hard workflow checkpoints between steps.
Lobster provides a command-line interface with several core commands. The exec command runs OS commands with optional stdin feeding in raw, JSON, or JSONL formats. Data shaping commands include where, pick, and head for filtering and transforming data. Rendering options provide json and table output formats. An approve command implements approval gates that function as TTY prompts or emit structured responses for OpenClaw integration. The graph command visualizes workflow structure before execution, supporting mermaid, dot, and ASCII output formats to show steps as nodes, data-flow edges from stdin references, conditional dependencies, and approval gates as diamond-shaped nodes.
Workflow files support multiple step types with shared argument, environment, and results models. Steps can reference prior step outputs via $step.stdout or $step.json for data passing without temporary files. Conditional execution is possible through when and condition directives. Steps support retry logic, timeout configuration in milliseconds, and on_error handlers for transient failure recovery. Approval steps can enforce identity constraints through required_approver, require_different_approver, and initiated_by fields, with environment variables LOBSTER_APPROVAL_INITIATED_BY and LOBSTER_APPROVAL_APPROVED_BY providing runtime identity information.
Lobster integrates with language models through native pipeline stages. The llm.invoke command calls models directly with provider resolution from command-line flags, environment variables, or auto-detection. Built-in providers include OpenClaw via OPENCLAW_URL and OPENCLAW_TOKEN, Pi via LOBSTER_PI_LLM_ADAPTER_URL, and HTTP via LOBSTER_LLM_ADAPTER_URL. The openclaw.agent command delegates to configured OpenClaw agents, handling agent identity, model defaults, sessions, and authentication. Workflow cost tracking uses static pricing tables with optional overrides via LOBSTER_LLM_PRICING_JSON for per-model pricing in USD per million tokens.
Development uses pnpm for package management, with TypeScript compilation to a dist directory before test execution. The roadmap includes shipping Lobster as an optional OpenClaw plugin tool to expand its integration capabilities.
