Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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.
