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 the ref selected by KAIZEN_RUNTIME_REF (main by default). Because dist/ is committed, a refresh normally installs runtime dependencies and runs the CLI that ships with the commit; it builds only when the checked-out commit has no dist/. The clone is hard-reset to the target ref, so it is disposable build output and never 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.

dist/ is committed so that npm install -g "github:kaizen-agents-org/kaizen-loop#<tag>" yields a working CLI with no build step on the adopter's machine. npm run check:dist rebuilds and fails when the committed output is stale; CI runs it on every change. Run npm run build and commit the regenerated files when it reports a difference.

KAIZEN_RUNTIME_REF selects which upstream ref that clone follows. It defaults to main, which is what dogfood repositories want: they exercise unreleased code on purpose. External adopters set it to the release tag pinned by onboarding/versions.json (for example v0.1.0), so a scheduled run cannot pick up code that has not been released. A value starting with v is fetched and checked out as a tag; anything else is followed as a branch.

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 a third-party installation, start with the third-party adopter guide. Its recommended GitHub Actions path adds .kaizen/config.yml and one caller workflow; provider generation, credential-free verification, and publish-only permissions run in separate jobs. The lower-level workflow contract is documented in docs/14-github-actions.md.

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.

Kaizen requires structured verifier --version --json provenance. Local and fleet runs resolve the configured canonical repository/ref independently and stop before builder execution unless the expected, build, and runtime commits match and the runtime is clean. Legacy plain version output cannot prove freshness and is rejected. The reusable Actions workflow currently supports only the default kaizen-agents-org/verifier trust root and compares provenance with its audited verifier checkout commit; custom verifier trust roots require a correspondingly trusted workflow checkout.

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.
• docs/15-third-party-adopter-guide.md: third-party prerequisites, installation, safe operation, troubleshooting, and rollback.