Joelclaw agent-loop

Start, monitor, and cancel durable multi-agent coding loops via Inngest. Use when the user wants to run autonomous coding workloads, execute a PRD with multiple stories, kick off an AFK coding session, have agents implement features from a plan, or manage running loops. Triggers on "start a coding loop", "run this PRD", "implement these stories", "go AFK and code this", "check loop status", "cancel the loop", "joelclaw loop", or any request for autonomous multi-story code execution.

install

source · Clone the upstream repo

git clone https://github.com/joelhooks/joelclaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/joelhooks/joelclaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/agent-loop" ~/.claude/skills/joelhooks-joelclaw-agent-loop && rm -rf "$T"

manifest: skills/agent-loop/SKILL.md

source content

Agent Loop

Run durable PLANNER→IMPLEMENTOR→REVIEWER→JUDGE coding loops via Inngest. Each story in a PRD gets independently implemented, tested, and judged. Survives crashes. Every step is a traceable Inngest run.

After starting a loop, use the loop-nanny skill for monitoring, triage, post-loop cleanup, and knowing when to intervene.

Quick Start

# Start a loop
joelclaw loop start --project /path/to/project --prd prd.json --max-retries 2

# Check status
joelclaw loop status [LOOP_ID]

# Cancel
joelclaw loop cancel LOOP_ID

The

joelclaw

CLI is the primary interface. Run with

bun run packages/cli/src/cli.ts loop start ...

from the monorepo root.

PRD Format

Create a

prd.json

in the project root:

{
  "title": "Feature Name",
  "description": "What we're building",
  "stories": [
    {
      "id": "S1",
      "title": "Short title",
      "description": "What to implement. Be specific about files, patterns, behavior.",
      "acceptance_criteria": [
        "Criterion 1 — must be verifiable by automated test",
        "Criterion 2 — must be checkable by typecheck/lint"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

Story writing tips:

Acceptance criteria must be machine-verifiable (tests, typecheck, lint)
Lower priority number = runs first
Keep stories small and atomic — one concern per story
Include file paths in descriptions when possible
```
passes
```
flips to
```
true
```
when JUDGE approves;
```
skipped: true
```
added on max retry exhaustion
Runtime preflight normalizes legacy aliases (
```
acceptance
```
,
```
acceptanceCriteria
```
) to
```
acceptance_criteria
```
, but malformed stories still fail fast with explicit schema errors — keep PRDs canonical.

Pipeline Flow

joelclaw loop start → agent/loop.start event
  → PLANNER reads prd.json, finds next unpassed story
    → IMPLEMENTOR spawns codex/claude/pi, commits changes
      → REVIEWER writes tests from acceptance criteria (independently — does NOT read implementation)
        → JUDGE: all green? → mark passed, next story
                 failing?   → retry with feedback (up to maxRetries)
                 exhausted? → skip, flag for human review, next story
  → All done → agent/loop.complete

progress.txt

Create a

progress.txt

in the project root with a

## Codebase Patterns

section at the top. This is read by the implementor for project context and appended by the judge after each story. Defends against context loss across fresh agent instances.

## Codebase Patterns

- Runtime: Bun, not Node
- Tests: bun test
- Key files: src/index.ts, src/lib/...

## Progress

(stories will be appended here)

Infrastructure

Canonical source:

~/Code/joelhooks/joelclaw/packages/system-bus/

(monorepo)

Inngest functions:

agent-loop-plan

agent-loop-implement

agent-loop-review

agent-loop-judge

agent-loop-complete

agent-loop-retro

Inngest server: k8s StatefulSet at localhost:8288
Loop --project target: Always use
```
~/Code/joelhooks/joelclaw/packages/system-bus
```
(the monorepo).

Apply worker changes:

~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh

Verify functions:
```
joelclaw functions
```
View runs:
```
joelclaw runs -c
```
Inspect a run:
```
joelclaw run RUN_ID
```

Single-source deployment flow

The monorepo is the source of truth for loop function code. After loop-related function changes merge, deploy the worker from the monorepo:

Run

~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh

Wait for rollout:

kubectl -n joelclaw rollout status deployment/system-bus-worker --timeout=180s

Refresh registration:
```
joelclaw refresh
```

Event Schema

All events carry

loopId

for tracing. Key events:

Event	Purpose
`agent/loop.start`	Kick off loop (loopId, project, prdPath, maxRetries, maxIterations)
`agent/loop.plan`	Planner re-entry (find next story)
`agent/loop.implement`	Dispatch to implementor (storyId, tool, attempt, feedback?)
`agent/loop.review`	Dispatch to reviewer (storyId, commitSha, attempt)
`agent/loop.judge`	Dispatch to judge (testResults, feedback, attempt)
`agent/loop.complete`	Loop finished (summary, counts)
`agent/loop.cancel`	Stop the loop
`agent/loop.story.pass`	Story passed
`agent/loop.story.fail`	Story skipped after max retries

Tool Assignment

Default: codex for implementation, claude for review. Override per-story via

toolAssignments

in the start event:

{
  "toolAssignments": {
    "S1": { "implementor": "claude", "reviewer": "claude" },
    "S2": { "implementor": "codex", "reviewer": "pi" }
  }
}

Known Gotchas

Concurrency keys use CEL expressions (
```
event.data.project
```
), not
```
{{ }}
```
templates
```
loop
```
is reserved in CEL — don't use in concurrency key strings

Use explicit Codex permissions:

codex exec --ask-for-approval never --sandbox danger-full-access PROMPT

(no

-q

flag)

Worker changes require a k8s deploy (
```
k8s/publish-system-bus-worker.sh
```
)
Docker must be running for Inngest server (
```
open -a OrbStack
```
)
Large tool output uses claim-check pattern (written to
```
/tmp/agent-loop/{loopId}/
```
)

Logging

Every story attempt is logged via slog:

slog write --action "story-pass" --tool "agent-loop" --detail "Story title (ID) passed on attempt N" --reason "details"

Actions:

story-pass

story-retry

story-skip

build-complete

Source Files

File	Purpose
`~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/client.ts`	Event type definitions
`~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/utils.ts`	PRD parsing, git, cancellation, claim-check
`~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/plan.ts`	PLANNER
`~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/implement.ts`	IMPLEMENTOR
`~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/review.ts`	REVIEWER
`~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/judge.ts`	JUDGE
`~/Code/joelhooks/joelclaw/packages/system-bus/src/serve.ts`	Worker registration
`~/Code/joelhooks/joelclaw/packages/cli/src/cli.ts`	joelclaw CLI (loop subcommands)