The joelclaw CLI is the primary operator interface to the entire joelclaw system: event bus (Inngest), gateway, observability (OTEL), agent loops, subscriptions, and more. Built with @effect/cli, returns HATEOAS JSON envelopes.
If the CLI crashes, that's the highest priority fix.
The legacy joelclaw log write / slog JSONL journal is retired. Emit/query structured runtime telemetry with joelclaw otel; record durable decisions and change receipts in Brain .svx. joelclaw logs remains the runtime log read/analyze surface.
--priority is deprecated compatibility metadata. Use --kind; the versioned routing table owns delivery.
Capability Adapter Paths (ADR-0169 phase 4)
mail, otel, recall, and subscribe now run through the CLI capability registry/adapter runtime while preserving their existing command UX and JSON envelopes.
Deploy
joelclaw deploy worker # dry-run deploy plan
joelclaw deploy worker --restart --execute # execute worker sync deployment
joelclaw deploy worker --restart --execute --force # force with active runs (disruptive)
Heal
joelclaw heal list
joelclaw heal run RUN_FAILED --phase fix --context '{"run-id":"01ABC"}'# dry-run
joelclaw heal run RUN_FAILED --phase fix --context '{"run-id":"01ABC"}' --execute # execute
Gateway
joelclaw gateway status # Gateway health + session info
joelclaw gateway events # Recent gateway events
joelclaw gateway test# Send test message through gateway
joelclaw gateway restart # Restart gateway daemon
joelclaw gateway stream # Live stream gateway events
Observer
observer is the canonical joelclaw Observer target. Do not guess panes from the default Herdr session, and do not treat it as a hidden special case. Resolve and manage it through the CLI first:
joelclaw observer status # Herdr protocol + Observer registry/session metadata
joelclaw observer resolve observer # Canonical target → named Herdr session + pane
joelclaw observer resolve dispatcher # Dispatcher pane in the Observer family
joelclaw observer cycle # Dry-run safe named-session cycle plan
joelclaw observer cycle --execute # Cycle only the named observer Herdr server, then rotate Observer
Use joelclaw observer resolve observer before scheduling or waking the Observer. If it fails with OBSERVER_TARGET_UNHEALTHY, run joelclaw observer status; if the Herdr protocol drifted, run joelclaw observer cycle --execute. joelclaw wake ... --target observer is the right wake target once resolve is healthy.
workload run admits into Redis, then Restate executes the stage through dagOrchestrator → dagWorker
dagWorker handlers: shell, infer, microvm
infer now runs pi inside the restate-worker k8s pod with mounted auth, skills, and identity
--stages-from is the explicit stage-DAG front door; dependency gates and cycle detection are real
Async runtime monitoring in pi
The loaded pi extension at packages/pi-extensions/inngest-monitor/index.ts now exposes runtime_jobs_monitor alongside inngest_send / inngest_runs.
Use it when you want a pi session to keep watch on the ADR-0217 runtime substrate while you do other work:
runtime_jobs_monitor {"action":"start","interval":5,"report":true} — start background polling of joelclaw jobs status
runtime_jobs_monitor {"action":"status"} — inspect the latest runtime snapshot
runtime_jobs_monitor {"action":"stop"} — stop the poller and send a final follow-up summary
The widget shows runtime health first (queue / Restate / Dkron / Inngest), then any followed Inngest runs underneath. Severity changes and meaningful workload-state changes emit OTEL and hidden follow-up messages for asynchronous report-back, so a healthy-but-now-held backlog does not stay silent.
joelclaw knowledge search "query"# Search system knowledge
joelclaw knowledge search "query" --type adr # Filter by type (adr|skill|lesson|pattern|retro|failed_target)
joelclaw knowledge sync# Re-index ADRs + skills from filesystem
joelclaw knowledge clear-failed <target> # Clear resolved failed targets
Brain/codebase patterns (browsable by agents):
ls ~/Vault/system/brain/codebase/ # List established patternscat ~/Vault/system/brain/codebase/<name>.md # Read a specific pattern
Subscriptions (ADR-0127)
joelclaw subscribe list # All feed subscriptions
joelclaw subscribe add <url> [--name N] # Add a feed
joelclaw subscribe remove <url> # Remove a feed
joelclaw subscribe check [--url URL] # Check feeds for new items
joelclaw subscribe summary # Summary of recent items
Agent Runtime Validation (ADR-0180)
Use this exact smoke test when validating roster dispatch end-to-end:
joelclaw agent list
joelclaw agent run coder "reply with OK" --timeout 20
joelclaw event <event-id>
Expected signal:
agent list includes builtin coder, designer, ops
event shows one Agent Task Run with status: COMPLETED
run output contains {"status":"completed", ...}
Failure handling:
Unknown agent roster entry: coder means runtime drift, not prompt failure.
Deploy latest system-bus-worker
Restart host worker process
Re-run the same 3-step smoke
If Inngest API is unreachable (localhost:8288), recover local control-plane first (Colima/Talos), then retry validation.
Brain-backed Recall
joelclaw recall "query about past context"# Search disposable Brain + observation projections
Brain .svx pages remain canonical. The Typesense observations and brain_graph_nodes collections are rebuildable projections, not a second memory store.
Discovery
joelclaw discover "https://example.com" --context "why this is interesting"
Agent Loops
# Start a loop
joelclaw loop start --project ~/Code/joelhooks/joelclaw \
--goal "Implement feature X" \
--context ~/Vault/docs/decisions/0XXX.md \
--max-retries 2
# Start with existing PRD
joelclaw loop start --project PATH --prd prd.json --max-retries 2
# Monitor
joelclaw loop status <LOOP_ID>
joelclaw loop status <LOOP_ID> -c # Compact: one line per story
joelclaw loop status <LOOP_ID> -v # Verbose: criteria, output paths
joelclaw watch <LOOP_ID> # Live: polls 15s, exits on completion
joelclaw watch # Auto-detects active loop# Management
joelclaw loop list # All loops in Redis
joelclaw loop cancel <LOOP_ID> # Stop + cleanup
joelclaw loop nuke dead # Remove completed loops from Redis
For vault-heavy or ADR-gardening tasks, use the dedicated vault skill.
Output Modes
Most commands support --compact/-c for plain text. Use compact for monitoring.
JSON (default) returns HATEOAS envelopes with next_actions.
Story Pipeline (ADR-0155)
3-stage pipeline: implement → prove → judge. Each story runs through the stages with Inngest durability.
# Fire a single story
joelclaw send agent/story.start -d '{
"prdPath": "/Users/joel/Code/joelhooks/joelclaw/prd.json",
"storyId": "CFP-2"
}'# ⚠️ ALWAYS use absolute path for prdPath — worker CWD is packages/system-bus/
PRD format (Zod-validated):
{"name":"Project Name","context":{},"stories":[{"id":"STORY-1","title":"What to build","description":"Details","priority":1,"acceptance":["criterion 1","criterion 2"],"files":["path/to/relevant/file.ts"]}]}
Critical:
context must be {} or object — NEVER null or string
Every story needs priority (number)
NEVER set retries: 0 on Inngest functions — breaks restart safety (ADR-0156)
joelclaw otel (otel_events in Typesense/ClickHouse)
Durable receipts
Brain .svx in the relevant registered root
Loop attempt output
/tmp/agent-loop/{loopId}/{storyId}-{attempt}.out
Building the CLI
cd ~/Code/joelhooks/joelclaw
bun build packages/cli/src/cli.ts --compile --outfile ~/.bun/bin/joelclaw
Test after every change:
joelclaw status
joelclaw send --help
joelclaw runs --count 1
CLI commands are in packages/cli/src/commands/, one file per command. Follow the cli-design skill. Heavy deps must be lazy-loaded — top-level import crashes are unacceptable.
