kaizen

Run and share kaizen so you can see how coding agents behave in real time, run retros on that stream, and turn it into strategies to improve your own repo. Unifies Cursor, Claude Code, and Codex. One SQLite store and one CLI; redact before any sync, and only sync on your terms.

Narrative guides and references live in this repository under docs/. The crate is on crates.io as kaizen-cli (cargo install kaizen-cli installs the kaizen binary); the Rust API is on docs.rs/kaizen-cli. Long-form markdown stays in this repo. See Install for cargo install, git clone, and PATH.

Why

• Cost visibility — tokens and USD per session, per model, per agent.
• Session history — searchable, live-tailable, across all three agents.
• 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 — self-host, laptop, or a shared place your team can use; tailable session streams; you decide 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.

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 both 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.