JoelClaw CLI
joelclaw.com- Category
- AI Agents
- Rank
- No. 2926Tools index
Previous survey · No. 2846 ·
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Agent Building
- Interfaces
- CLI
- Builder
- @joelclaw
- GitHub
- 65 stars
- Date
About
A CLI tool designed specifically for AI agents that returns JSON-structured output with HATEOAS navigation. Enables agents to interact with complex systems through standardized command templates and contextual next actions.
What it does
This is the operator command line for one developer's personal AI infrastructure: a single binary that fronts a home Kubernetes cluster, durable workflow engines, a search index, a messaging gateway and sandboxed coding agents. Every command prints one machine-readable envelope saying whether it succeeded, what it returned, and which follow-up commands make sense next, so an agent can walk the system without reading help text. A companion TypeScript library gives other programs the same surface, either by shelling out or by calling the adapters in-process.
Why it's ranked here
The interesting part is the design pattern, not the product. Calling the bare command returns a health check, recent workflow runs and a full map of about sixty command roots with their syntax, plus suggested next steps. Errors carry deterministic codes, and a recovery command maps those codes to runbooks. That is a worked, large example of shaping a CLI for agents instead of humans. As a tool to install, it is much weaker: it is wired to its author's own services and machines.
What's good
The response contract is enforced across a big surface, not sketched. The companion library parses the same envelope, exposes typed methods for status, deploys, logging, notifications, secrets leasing, telemetry search and recall, and separates process failures, failed envelopes and in-process adapter failures into distinct error types. Its default transport tries in-process first and falls back to spawning the binary. The docs spell out behavior carefully, for example an auth probe that reports token length and format but never prints raw tokens, and a fleet command that is explicitly read-only.
Tradeoffs
The root README is the unedited Turborepo starter template and says nothing about this project, so the real documentation lives in a docs folder. The package is marked private and the architecture notes describe one always-on Mac Mini running a single-node Kubernetes cluster, a NAS and a Tailscale network. Commands assume that stack: Inngest, Restate, Redis, Typesense and a local personal data server. No license file appears among the files read. Adopting the binary as-is is not realistic; borrowing its conventions is.
How to use it well
Treat it as a reference implementation. If you are building a command line that coding agents will drive, read the CLI contract document and the root command's output shape, then copy the envelope, the next-step hints and the error-code-to-runbook mapping into your own tool. The companion library is a useful model for giving programs parity with the shell without duplicating logic. It does not cover generic agent tooling you can point at your own infrastructure, and it ships no setup path for anyone else's machines.
Technical notes+
docs/cli.md defines the contract: every response is an envelope of ok, command, result and next_actions, errors go through respondError with deterministic codes, and heavy dependencies load lazily so commands that do not need Inngest survive a missing INNGEST_EVENT_KEY. packages/cli/src/cli.ts builds the root with @effect/cli on Bun and emits a respond() envelope listing command syntax and next actions. packages/sdk/src/index.ts exports createJoelclawClient, runbook helpers (RUNBOOK_ERROR_CODES, resolveRunbookCommand) and JoelclawProcessError, JoelclawEnvelopeError and JoelclawCapabilityError; transports are subprocess, inprocess and hybrid (default). docs/architecture.md describes hexagonal @joelclaw/* packages with the CLI as a thin composition root. package.json is private, pnpm workspaces over apps and packages, Node 18 or newer, with Turbo builds.
Observed
- Language
- TypeScript, run on Bun
- Interfaces
- CLI binary plus a TypeScript SDK with subprocess, in-process and hybrid transports
- CLI framework
- @effect/cli
- Packaging
- Private pnpm workspace monorepo; not published as a standalone package
- Output format
- JSON envelope with ok, command, result and next_actions on every command
- Documentation
- Root README.md is the default Turborepo starter; CLI contract documented in docs/cli.md
- Runtime requirements
- Built around Inngest, Restate, Redis, Typesense and a single-node Kubernetes cluster
- License
- No license file among the files read
Read from README.md, package.json, docs/cli.md, docs/architecture.md, packages/cli/src/cli.ts, packages/cli/src/capabilities/index.ts, packages/sdk/src/index.ts, packages/inference-router/src/index.ts, SECURITY_SUPPLY_CHAIN.md, AGENTS.md.
What it can do
Execute CLI commands with structured JSON responses
Command line instructions → JSON-formatted results
Generate HATEOAS navigation links for command sequences
Current command context → Hypermedia links showing available next actions
Process commands using standardized templates
Raw command parameters → Templated command structure
Provide contextual next action recommendations
Current system state and command history → Suggested follow-up commands and workflows
Interface with complex systems through AI agent protocols
System integration requests → Standardized agent-readable responses
Structure unformatted CLI output into machine-readable format
Raw command line output → Structured JSON data with metadata
Tags
Tech Stack
Media
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.