kaizen-loop

kaizen-loop is the local TypeScript CLI that coordinates Kaizen Agents work from GitHub Issues to ready-for-review pull requests.

It owns orchestration, not implementation quality by itself: it selects issues, prepares isolated workspaces, invokes builder-agent, runs repository verification commands, invokes verifier, applies repository policy, and reports the result back to GitHub.

What It Does

The Phase 2 implementation supports builder-agent-based fixes, verifier review, resumable per-issue git worktrees and checkpoint draft PRs, parallel issue processing, PR-first reflection followed by the vendored pr-guardian skill, explicit hybrid/direct reflection opt-ins when verifier is disabled, verification retries, YAML-configured scheduler jobs, opt-in issue queueing, user-triggered backlog improvement runs, and operational status commands. kaizen watch remains a later-phase feature.

Canonical repositories

Issues and pull requests for this project are tracked in kaizen-agents-org/kaizen-loop. Local development checkouts should use the org repository as their source-of-truth remote. Personal forks are fine as additional contributor remotes, but they are not the canonical issue/PR location.

The current CLI supports the issue-to-PR loop used by Kaizen Agents:

flowchart LR
    Issue["GitHub Issue<br/>kaizen label"] --> Select["select issue<br/>priority + queue rules"]
    Select --> Workspace["isolated worktree<br/>fresh or resumed branch"]
    Workspace --> Builder["builder-agent<br/>implementation"]
    Builder --> Verify["commands.verify<br/>tests / typecheck / build"]
    Verify --> Gate["verifier<br/>gate verdict"]
    Gate --> Policy["policy decision<br/>paths + labels + diff size"]
    Policy --> PR["ready-for-review PR"]
    Policy --> Direct["direct commit<br/>only when allowed"]
    Policy --> Human["needs-human handoff"]

    Verify -->|failed and retries left| Builder
    Gate -->|block_pr or needs_context| Builder

Loading

The runtime behavior is controlled by .kaizen/config.yml in each target repository. See docs/03-config-spec.md for the full schema.

Component Boundaries

flowchart TB
    KL["kaizen-loop"]
    BA["builder-agent"]
    VF["verifier"]
    GH["GitHub via gh"]
    FS["~/.kaizen local state"]
    Repo["target repository"]

    KL -->|"reads .kaizen/config.yml"| Repo
    KL -->|"creates worktrees, branches, commits"| FS
    KL -->|"stdin prompt + KAIZEN_BUILD_RESULT_PATH"| BA
    KL -->|"runs commands.verify"| Repo
    KL -->|"stdin prompt + KAIZEN_VERIFIER_RESULT_PATH"| VF
    KL -->|"issues, comments, labels, PRs"| GH

Loading

Commands

Command	Purpose
kaizen init	Install .kaizen/config.yml, issue template, labels, registry entry, workspace, and default scheduler registration. Use kaizen scheduler sync to re-sync or repair scheduler jobs.
kaizen run	Run the maintenance pipeline once. Use --dry-run to inspect issue selection without modifying workspaces or GitHub.
kaizen fix <issue>	Process one existing issue immediately with the same safety gates as scheduled runs.
kaizen report <title>	Create a Kaizen issue; --now creates and immediately processes it.
kaizen smoke	Run a controlled sandbox issue-to-PR smoke pass and save readiness artifacts.
kaizen queue / kaizen unqueue	Add or remove queued execution approval labels for opt-in selection mode.
kaizen improve	Plan and run an immediate improvement pass over selected or queued issues.
kaizen goal	Create and run a multi-iteration goal that plans scoped issues, processes them, evaluates progress, and stops when done or blocked.
kaizen status	Show registry state and latest run summary. Use --metrics for aggregate counters.
kaizen scheduler	Inspect, update, sync, and disable scheduled jobs.
kaizen fleet	Rebuild registry, workspaces, labels, scheduler jobs, and optionally verify fleet workspaces after upgrading Kaizen Loop.
kaizen logs	Print latest or selected run logs from ~/.kaizen.
kaizen doctor	Check local setup, required labels, workspaces, and external commands.
kaizen list	List registered projects.
kaizen watch	Reserved for Phase 4; currently returns a not-implemented error.

Most commands accept --project <slug> and --json. run, fix, and improve accept --agent claude|codex to override the repository default for the current run.

Scheduler synchronization installs a stable operator launcher at $KAIZEN_HOME/bin/kaizen and a scheduled wrapper at $KAIZEN_HOME/bin/run-scheduled.sh. Use the stable launcher for doctor, fleet, monitor checks, and other operator commands; add $KAIZEN_HOME/bin before global npm locations on PATH if the short kaizen command is required. Both operator and scheduled commands refresh a dedicated runtime clone under $KAIZEN_HOME/runtime/kaizen-loop from origin/main. It installs dependencies and rebuilds only when the main commit changes, then runs the requested job with that verified build. The dedicated clone keeps automatic updates from switching or resetting a developer checkout. An update or build failure stops the scheduled run or operator command instead of silently using stale code. doctor --json and fleet --json include the selected runtime commit and directory.

Quickstart

npm install
npm test
npm run typecheck
npm run build

For local CLI development without installing the package:

npm run dev -- --help
npm run dev -- run --dry-run --json

For a target repository:

kaizen init --agent codex --schedule 02:00
kaizen scheduler sync
export PATH="${KAIZEN_HOME:-$HOME/.kaizen}/bin:$PATH"
kaizen doctor
kaizen report "Fix stale config reload" --body "Observed during local dogfooding" --priority P2 --queue
kaizen run --dry-run
kaizen fix 42 --json
kaizen smoke --project sandbox-repo --yes --json
kaizen goal create "Improve onboarding reliability" --success "npm test and npm run typecheck pass" --json
kaizen goal run <goal-id> --yes --json

After upgrading from a release without the stable operator launcher, run npm run build && node dist/cli.js scheduler sync once from the upgraded kaizen-loop checkout for each registered project. Subsequent invocations atomically refresh both installed launchers from the self-updating runtime checkout.

For an ephemeral GitHub Actions deployment, see docs/14-github-actions.md. External repositories add .kaizen/config.yml and one caller workflow; provider generation, credential-free verification, and publish-only permissions run in separate jobs.

For this repository's own dogfooding loop:

npm run dogfood:sync
npm run dogfood:verify

Runtime Requirements

The CLI delegates external work instead of embedding tokens or provider SDKs:

• git for workspace, branch, diff, commit, push, and worktree operations.
• gh for issue, label, comment, and PR operations.
• builder-agent on PATH when .kaizen/config.yml uses the default builder command.
• verifier on PATH when verifier.enabled: true.
• codex for the PR guardian workflow when guardian.enabled: true.

KAIZEN_HOME may be set to override the default local state directory (~/.kaizen). The local state contains the registry, project workspaces, locks, logs, and latest run summaries; it should not be committed to target repositories.

When verifier provides --version --json, Kaizen records its build/runtime provenance and stops before builder execution if a linked checkout is newer than the compiled verifier. Legacy plain version output remains supported and is recorded as an unverifiable compatibility diagnostic.

Repository Contract

Target repositories opt in through committed configuration:

version: 1
commands:
  setup: "npm ci"
  verify:
    - "npm test"
    - "npm run typecheck"
policy:
  mode: pr-only

The important contract points are:

• commands.setup runs after workspace reset and before issue branches are prepared.
• commands.verify is the mechanical gate; every command must pass before PR/direct reflection continues.
• builder.command receives the issue prompt on stdin and writes builder.resultPath.
• verifier.command receives a verifier prompt on stdin and writes verifier.resultPath.
• The intake gate treats issues as evidence, not orders: live workflows targeting another repository are handed to a human, while unsupported source-of-truth syncs, guardrail regressions, missing context, and already-covered work are commented and skipped before builder-agent runs.
• guardian.command runs the vendored pr-guardian workflow after PR creation; guardian.mode: async persists resumable jobs under ~/.kaizen/projects/<slug>/guardian/jobs/. Durable reconciliation also adopts same-repository generated sync PRs carrying <!-- kaizen-pr-guardian:managed -->, runs them in isolated worktrees, and re-observes successful open jobs so a same-head late review reactivates the loop. In repositories that require conversation resolution, outdated unresolved threads still block merging until they are resolved.
• safety.minFreeDiskMb and safety.envAllowlist control workspace preflight capacity and the environment exposed to shell, builder, verifier, guardian, and goal commands.
• policy.mode, protected paths, forbidden paths, labels, diff size, and verifier output decide whether the result becomes a PR, a direct commit, or a human handoff.

Documentation

Start with docs/README.md. The most useful implementation-facing references are:

• docs/02-cli-spec.md: command behavior and options.
• docs/03-config-spec.md: .kaizen/config.yml schema.
• docs/04-nightly-pipeline.md: run pipeline and retry behavior.
• docs/07-safety.md: guardrails, locks, protected paths, and failure modes.
• docs/09-instant-run.md: fix, report --now, and improve.
• docs/10-skills.md: shared Kaizen skills vendored into target repositories.
• docs/11-goals.md: Goal runner behavior and agent-facing contract.
• docs/13-sandbox-smoke.md: controlled sandbox smoke runs and readiness artifacts.
• docs/14-github-actions.md: reusable issue-labeled workflow and credential-separated ephemeral execution.