kaizenai 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Jake Mor
+
+Permission is hereby granted, free of charge, to any person other than Jacob
+Eiting and RevenueCat, Inc. obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+<p align="center">
+  <img src="assets/icon.png" alt="Kaizen" width="80" />
+</p>
+
+<h1 align="center">Kaizen</h1>
+
+<p align="center">
+  <strong>A beautiful web UI for Claude Code, Codex, Gemini, and Cursor</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/kaizenai"><img src="https://img.shields.io/npm/v/kaizenai.svg?style=flat&colorA=18181b&colorB=f472b6" alt="npm version" /></a>
+</p>
+
+<br />
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/screenshot.png" />
+    <source media="(prefers-color-scheme: light)" srcset="assets/screenshot-light.png" />
+    <img src="assets/screenshot.png" alt="Kaizen screenshot" width="800" />
+  </picture>
+</p>
+
+<br />
+
+## Quickstart
+
+```bash
+npx kaizenai
+```
+
+`kaizen` is already taken on npm, so the package name needs to stay `kaizenai` for now.
+
+After install, the command is still:
+
+```bash
+kaizen
+```
+
+`npx kaizenai` still requires Bun to be installed locally because the Kaizen runtime executes on Bun.
+
+If Bun isn't installed, install it first:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+Then run from any project directory:
+
+```bash
+kaizen
+```
+
+That's it. Kaizen opens in your browser at [`localhost:3210`](http://localhost:3210).
+
+## Features
+
+- **Multi-provider support** — switch between Claude, Codex, Gemini, and Cursor from the chat input, with per-provider model selection, plan mode support, and provider-specific controls
+- **Project-first sidebar** — chats grouped under projects, with live status indicators (idle, running, waiting, failed)
+- **Drag-and-drop project ordering** — reorder project groups in the sidebar with persistent ordering
+- **Local project discovery** — auto-discovers projects from Claude and Codex local history
+- **Rich transcript rendering** — hydrated tool calls, collapsible tool groups, plan mode dialogs, and interactive prompts with full result display
+- **Quick responses** — lightweight structured queries (e.g. title generation) via Claude Haiku with automatic provider fallback
+- **Plan mode** — review and approve agent plans before execution
+- **Persistent local history** — refresh-safe routes backed by JSONL event logs and compacted snapshots
+- **Auto-generated titles** — chat titles generated in the background via Claude Haiku
+- **Session resumption** — resume agent sessions with full context preservation
+- **WebSocket-driven** — real-time subscription model with reactive state broadcasting
+
+## Architecture
+
+```
+Browser (React + Zustand)
+    ↕  WebSocket
+Bun Server (HTTP + WS)
+    ├── WSRouter ─── subscription & command routing
+    ├── AgentCoordinator ─── multi-provider turn management
+    ├── ProviderCatalog ─── provider/model/effort normalization
+    ├── QuickResponseAdapter ─── structured queries with provider fallback
+    ├── EventStore ─── JSONL persistence + snapshot compaction
+    └── ReadModels ─── derived views (sidebar, chat, projects)
+    ↕  stdio
+Claude Code / Codex / Gemini CLI / Cursor Agent ACP (local processes)
+    ↕
+Local File System (~/.kaizen/data/, project dirs)
+```
+
+**Key patterns:** Event sourcing for all state mutations. CQRS with separate write (event log) and read (derived snapshots) paths. Reactive broadcasting — subscribers get pushed fresh snapshots on every state change. Multi-provider agent coordination with tool gating for user-approval flows. Provider-agnostic transcript hydration for unified rendering.
+
+## Requirements
+
+- [Bun](https://bun.sh) v1.3.5+
+- A working [Claude Code](https://docs.anthropic.com/en/docs/claude-code) environment
+- _(Optional)_ [Codex CLI](https://github.com/openai/codex) for Codex provider support
+- _(Optional)_ [Gemini CLI](https://github.com/google-gemini/gemini-cli) for Gemini provider support
+- _(Optional)_ [Cursor CLI / Agent](https://cursor.com/downloads) for Cursor provider support (`agent acp`)
+
+Embedded terminal support uses Bun's native PTY APIs and currently works on macOS/Linux.
+
+## Install
+
+Install Kaizen globally:
+
+```bash
+npm install -g kaizenai
+```
+
+This installs the `kaizen` command globally.
+
+Or run it without installing:
+
+```bash
+npx kaizenai
+```
+
+Because the npm package name is `kaizenai`, `npx kaizen` is not available unless the `kaizen` package name becomes available in the registry. If Bun is missing, `kaizen` and `npx kaizenai` will print a setup message telling the user to install Bun first.
+
+If Bun isn't installed, install it first:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+Or clone and build from source:
+
+```bash
+git clone https://github.com/jayleaton/kaizen.git
+cd kaizen
+bun install
+bun run build
+```
+
+## Usage
+
+```bash
+kaizen                  # start with defaults (localhost only)
+kaizen --port 4000      # custom port
+kaizen --no-open        # don't open browser
+```
+
+Default URL: `http://localhost:3210`
+
+### Network access (Tailscale / LAN)
+
+By default Kaizen binds to `127.0.0.1` (localhost only). Use `--host` to bind a specific interface, or `--remote` as a shorthand for `0.0.0.0`:
+
+```bash
+kaizen --remote                     # bind all interfaces — browser opens localhost:3210
+kaizen --host dev-box               # bind to a specific hostname — browser opens http://dev-box:3210
+kaizen --host 192.168.1.x           # bind to a specific LAN IP
+kaizen --host 100.64.x.x            # bind to a specific Tailscale IP
+```
+
+When `--host <hostname>` is given, the browser opens `http://<hostname>:3210` automatically. Other machines on your network can connect to the same URL:
+
+```
+http://dev-box:3210
+```
+
+## Development
+
+```bash
+bun run dev
+```
+
+The same `--remote` and `--host` flags can be used with `bun run dev` for remote development.
+Use `bun run dev --port 4000` to run the Vite client on `4000` and the backend on `4001`.
+
+Or run client and server separately:
+
+```bash
+bun run dev:client   # http://localhost:5174
+bun run dev:server   # http://localhost:5175
+```
+
+## Scripts
+
+| Command              | Description                  |
+| -------------------- | ---------------------------- |
+| `bun run build`      | Build for production         |
+| `bun run check`      | Typecheck + build            |
+| `bun run dev`        | Run client + server together |
+| `bun run dev:client` | Vite dev server only         |
+| `bun run dev:server` | Bun backend only             |
+| `bun run start`      | Start production server      |
+
+## Project Structure
+
+```
+src/
+├── client/          React UI layer
+│   ├── app/         App router, pages, central state hook, socket client
+│   ├── components/  Messages, chat chrome, dialogs, buttons, inputs
+│   ├── hooks/       Theme, standalone mode detection
+│   ├── stores/      Zustand stores (chat input, preferences, project order)
+│   └── lib/         Formatters, path utils, transcript parsing
+├── server/          Bun backend
+│   ├── cli.ts       CLI entry point & browser launcher
+│   ├── server.ts    HTTP/WS server setup & static serving
+│   ├── agent.ts     AgentCoordinator (multi-provider turn management)
+│   ├── gemini-acp.ts  Gemini ACP JSON-RPC client
+│   ├── cursor-acp.ts  Cursor ACP JSON-RPC client
+│   ├── codex-app-server.ts  Codex App Server JSON-RPC client
+│   ├── provider-catalog.ts  Provider/model/effort normalization
+│   ├── quick-response.ts    Structured queries with provider fallback
+│   ├── ws-router.ts WebSocket message routing & subscriptions
+│   ├── event-store.ts  JSONL persistence, replay & compaction
+│   ├── discovery.ts Auto-discover projects from Claude and Codex local state
+│   ├── read-models.ts  Derive view models from event state
+│   └── events.ts    Event type definitions
+└── shared/          Shared between client & server
+    ├── types.ts     Core data types, provider catalog, transcript entries
+    ├── tools.ts     Tool call normalization and hydration
+    ├── protocol.ts  WebSocket message protocol
+    ├── ports.ts     Port configuration
+    └── branding.ts  App name, data directory paths
+```
+
+## Data Storage
+
+All state is stored locally at `~/.kaizen/data/`:
+
+| File             | Purpose                                   |
+| ---------------- | ----------------------------------------- |
+| `projects.jsonl` | Project open/remove events                |
+| `chats.jsonl`    | Chat create/rename/delete events          |
+| `messages.jsonl` | Transcript message entries                |
+| `turns.jsonl`    | Agent turn start/finish/cancel events     |
+| `snapshot.json`  | Compacted state snapshot for fast startup |
+
+Event logs are append-only JSONL. On startup, Kaizen replays the log tail after the last snapshot, then compacts if the logs exceed 2 MB.
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=jayleaton%2Fkaizen&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=jayleaton/kaizen&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=jayleaton/kaizen&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=jayleaton/kaizen&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## License
+
+[MIT](LICENSE)

package/bin/kaizen

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Kaizen requires Bun 1.3.5+ to run." >&2
+  echo "Install Bun from https://bun.sh and then retry." >&2
+  exit 1
+fi
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ "${KAIZEN_CLI_MODE:-}" = "child" ]; then
+  exec bun "$SCRIPT_DIR/src/server/cli.ts" "$@"
+else
+  exec bun "$SCRIPT_DIR/src/server/cli-supervisor.ts" "$@"
+fi