kaizen

Kaizen captures coding-agent sessions — Cursor, Claude Code, Codex, OpenClaw, Goose, OpenCode, Copilot — into per-workspace SQLite while a machine registry (~/.kaizen/machine.db) records every repo you kaizen init, so doctor, retention, and --all-workspaces stay coherent across the host. Local ingest is the default (transcript tails, Cursor / Claude Code / OpenClaw hooks, optional Anthropic HTTP proxy with token-accurate logging and context policy). When you enable team sync and a PostHog or Datadog query provider, summary, metrics, guidance, and retro can --source mixed (or provider) and kaizen telemetry pull to reconcile rollups with vendor-side events cached beside your rows. Then Kaizen closes the loop most tools skip: a heuristic retro engine that ranks improvement bets by tokens-saved-per-effort, and an A/B experiment framework that measures whether each bet worked. Nothing leaves disk until you say so; redact-first sync stays the team path.

Narrative guides and references live in this repository under docs/. The CLI is published on crates.io as kaizen-cli. Install with cargo install kaizen-cli --locked, or build from a git clone if you are developing the project. The Rust API is on docs.rs/kaizen-cli. Long-form markdown stays in this repo. See Install for PATH, Homebrew, and troubleshooting.

Agile retrospectives for coding agents

Agents are opaque. They burn tokens on files you didn't expect, loop on module boundaries you haven't mapped, and load skills that never fire. Most tools show you what happened. Kaizen tells you what to change — and proves whether the change worked.

The loop is observe → summarise → propose → measure. Each step is a real command.

Observe across three ingest tiers, zero agent restarts. kaizen init wires transcript tails (file notifications on agent JSONL directories) and hooks: .cursor/hooks.json, .claude/settings.json, and OpenClaw’s ~/.openclaw/hooks/kaizen-events/handler.ts (created or backed up idempotently). The optional LLM HTTP proxy goes further: run kaizen proxy run, set ANTHROPIC_BASE_URL=http://127.0.0.1:3847, and every Anthropic API call is logged with precise token counts — no changes to the agent. The proxy optionally applies a context policy (last_messages: 20 or max_input_tokens: 200000) that trims billed context before requests leave your machine.

Summarise at the repository level, not just the token level. Sessions and tool spans accumulate in a local SQLite WAL; optional provider pulls land correlated event-shaped rows in the same DB when [telemetry.query] is configured. The metrics pass walks git and your source tree to build a code graph (file_facts, repo_edges), so retros and experiments can answer: which files co-appear in long sessions, which module boundaries cause agent edit loops, which skills are loaded every turn but never triggered.

Propose with 30+ deterministic heuristics, no LLM required. kaizen retro --days 7 ranks bets by tokens_saved_per_week / effort_minutes. Each bet includes a hypothesis, estimated impact, evidence links (specific sessions and files), effort in minutes, and a ready-to-run apply command. Deterministic, formally specced in Quint, cheap to run on any schedule. The same engine ships as an agent skill: ask "what should I improve?" mid-session and kaizen surfaces the top bets inline without leaving your editor.

Measure with bootstrap statistics. kaizen exp new --bind git ties a hypothesis to a git commit boundary. Kaizen auto-classifies every subsequent session as control or treatment by walking git log. After the window closes, kaizen exp report shows control vs treatment sample sizes and medians, median delta with a 95% bootstrap CI (10k resamples, winsorized at p1/p99), and a pass/fail against your target. Works for skill additions, rule changes, and architecture refactors — anything you can pin to a commit.

Distribute with redact-first sync. Configure a shared team endpoint and kaizen ships redacted batches: Aho-Corasick secret scanning, env var stripping, absolute path normalization, and git email removal run on every event before it leaves disk. The redaction model is formally verified in a Quint spec. Sync is opt-in, idempotent (UUIDv7 dedup), and restartable after failures.

Optional local depth: post-stop test/lint snapshots and per-process CPU/RSS samples are off by default; enable in config for stricter retro signals without sending raw command output off disk (outcomes, system telemetry).

Why

• Cost visibility — tokens and USD per session, model, and agent; same rollups can merge local SQLite with vendor telemetry when sync + query provider are set (--source mixed).
• Session history — searchable, live-tailable, unified across Cursor, Claude Code, Codex, OpenClaw, and the other tailed agents in config.
• Host-level map — machine registry lists every inited workspace; --all-workspaces merges per-repo DBs on this machine without hand-maintained paths.
• Heuristic retro — weekly bets: what to change to make agents cheaper / faster.
• Experiments — A/B a rule, skill, or repo change against a real metric.
• Fits your topology — laptop or shared team endpoint; tailable streams; you choose when anything syncs and redact first.

Why kaizen over the alternatives

Kaizen is not a dashboard — it is an opinionated feedback loop: capture → summarise → propose change → measure. Start with kaizen init in any repo where you use a coding agent.

How it works (about 60 seconds)

Kaizen does not run the model. It observes agent activity: conversation and tool use land in local SQLite; optional HTTP proxy logging adds another path. A metrics pass ties sessions to file-level and graph facts so the CLI, TUI, retro, and experiments can reason about your repo, not just token totals. Read the full pipeline (with a diagram) in docs/telemetry-journey.md.

Demo

https://github.com/user-attachments/assets/3cf4ac40-cef7-480a-9bea-af69df06f3c6

Install

You need Rust 1.95+ (rustup). Git is only required for a source build.

Install the kaizen binary from crates.io with cargo install kaizen-cli --locked (step 1). To build from a clone of this repo instead, use step 2.

1. Install the CLI from crates.io (writes kaizen to ~/.cargo/bin, or $CARGO_HOME/bin):

   cargo install kaizen-cli --locked
   

   Or use Homebrew from a tap once you publish packaging/homebrew/kaizen-cli.rb to a homebrew-tap repo: brew tap <user>/tap && brew install kaizen-cli (installs the same kaizen binary). See docs/install.md.

2. Or build from a git clone (for contributors and --path installs):

   git clone https://github.com/marquesds/kaizen.git
   cd kaizen
   ./scripts/install-local.sh
   

   Equivalent: cargo install --path . --locked from the repo root (use --force to replace an existing install).

3. Confirm kaizen is on your PATH (rustup usually adds ~/.cargo/bin). If the shell cannot find kaizen, add that directory to PATH and open a new terminal.

4. Run kaizen in your own project (where you use Cursor / Claude Code / Codex), not only inside the kaizen repo:

   cd /path/to/your-project
   kaizen init
   

Step-by-step guide, uninstall, and troubleshooting: docs/install.md.

Quick start

kaizen init                  # scaffold .kaizen/ + wire .cursor/hooks.json + .claude/settings.json
kaizen doctor                # verify config, DB, and hook wiring
kaizen sessions list         # index sessions in the current repo
kaizen summary               # cost / agent / model rollup
kaizen tui                   # live session browser
kaizen retro --days 7        # weekly heuristic bets
kaizen exp new --name add-skill \
  --hypothesis "skill cuts tokens" --change "add .cursor/skills/x" \
  --metric tokens_per_session --bind git \
  --duration-days 14 --target-pct=-10

kaizen init creates Cursor, Claude Code, and OpenClaw hook files when absent and patches them idempotently when present. Re-running is safe; originals back up under .kaizen/backup/.

Full CLI reference: docs/usage.md. Guided walkthrough: docs/tutorial/README.md.

Docs

Status

Pre–1.0: breaking changes may appear in minor versions (see CHANGELOG.md). Feature set for the initial public line is shipped; follow the changelog for new work.

License

AGPL-3.0-or-later. Contributions are licensed under the same terms. See CONTRIBUTING.md.

Security disclosures: SECURITY.md.