diff --git a/README.md b/README.md index 9a218ce..7f84148 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,35 @@ Thanks. --- +## At a glance + +KeiSeiKit is scaffolding **around** Claude Code (and now Cursor / Continue / Zed via MCP). You still write your own agents, skills, and commits — the kit gives you the structure that keeps them coherent across sessions, machines, and parallel terminals. + +The shipped building blocks, in plain terms: + +- **Agents** assembled from reusable **blocks** (behavioural rules, stack profiles, deploy targets) so the same `kei-critic` persona works identically on every machine that installs the kit. +- **Hooks** at every tool-use boundary that refuse known-bad actions (pushing patent IP to github, hand-editing generated files, shipping an unverified citation) before they reach a commit. +- **Skills** that drive real work end-to-end via click-based `AskUserQuestion` wizards — spin up a project, compose a solution, scaffold CI, audit a session, set up nightly consolidation. +- **Rust primitives** covering the things Python ships wrongly: SQL migrations, changelog generation, config linting, cost ledgers, artifact handoff, firewall diffs, conflict scanners, and an offline markdown knowledge graph. +- **Exobrain mode** (v0.18+): a portable `brain` directory you can mount into any MCP-capable client via `keisei attach ` or `keisei mount ` (auto-attach-all). USB stick or cloud bucket — same memory + artifacts + personas across every client you run. +- **Sleep-sync** (v0.11+): your session traces push to a private git repo; a cloud-agent cron job does overnight REM-style pattern extraction; morning `git pull` shows the report. + +## What it solves + +| Problem you hit with vanilla Claude Code | What the kit adds | +|---|---| +| Every session starts cold — prior decisions forgotten | `kei-memory` session traces + cloud REM consolidation + `/self-audit` retrospective | +| Same mistake twice | `RULE 0.10 recurrence-escalate` skill + hook codifies it (rule file + wiki + block/enforce/warn/remind hook) | +| 4-8 parallel Claude terminals clobber each other | `kei-ledger` fork-tracking + `orchestrator-dirty-check` hook + `RULE 0.13` (orchestrator owns git) | +| Hallucinated API / fabricated citation shipped | `genesis-leak-guard` + `secrets-guard` + `citation-verify` hooks; Rust primitives replace Python where `None`-vs-`[]`-class bugs matter | +| Single-client lock-in (Claude Code OR Cursor OR Zed) | `keisei` CLI + 4 adapters — one brain, every client | +| No audit trail across branches | `kei-ledger` SQLite agent-fork history + `kei-store` memory-repo abstraction (GitHub / Forgejo / Gitea / FS / S3) | +| Drift between declared config and running state | `firewall-diff`, `ssh-check`, `kei-ci-lint`, `assemble-validate` hook | + +Not a replacement for Claude Code — a persistent structural layer over it. + +--- + ## What it is KeiSeiKit is a comprehensive drop-in toolkit for [Claude Code](https://claude.com/claude-code). It ships a curated set of composable behavioral blocks, a Rust assembler that builds agent `.md` files from TOML manifests deterministically, 10 pre-wired PreToolUse/PostToolUse hooks (three of them dedicated to RULE 0.14 session self-audit), 39 portable skills (including an interactive `/new-agent` wizard, 10 hub-and-spoke pipelines, and the `/self-audit` retrospective skill), **25 Rust primitive crates**, 13 opt-in shell primitives (plus 3 always-copied sleep-sync helpers), and 11 cross-tool bridge templates. Everything follows a Constructor Pattern: one file per concern, manifests as single source of truth, and the generated agent files are regenerated on every relevant edit. @@ -138,6 +167,49 @@ Every asset has a matching `.sha256` for integrity verification. Build det If you drop the binary at `~/.claude/agents/_primitives/_rust/target/release/kei-mcp-server--[.exe]` (the same layout `install.sh` uses for Rust primitives), re-running `install.sh` will detect it and skip any bun/npm build step. Set `KEI_SKIP_MCP_BUILD=1` to force-skip that step regardless of detection. +### The `keisei` CLI — multi-client exobrain mount (v0.19+) + +The `keisei` Rust crate is the entry-point that turns a **brain directory** (portable, filesystem-backed AI state — memory + artifacts + manifests + MCP server binaries) into an attachment on one or more AI clients in a single command. Brain layout: + +``` +/ +├── manifest.toml # schema_version, brain name, path pointers +├── memory/ # kei-memory git store (session traces, audit backlog) +├── artifacts/ # kei-artifact SQLite (typed handoff bundles) +├── manifests/ # user persona TOML library +└── bin/ + ├── kei-mcp-server-darwin-arm64 + ├── kei-mcp-server-linux-x64 + └── ... # per-platform binaries +``` + +Four CLI commands: + +| Command | What it does | +|---|---| +| `keisei attach [--client=X]` | Mount brain into a single detected client (default: first detected) | +| `keisei mount ` | Auto-attach to **every** detected client (Claude Code, Cursor, Continue, Zed) in one call | +| `keisei detach` | Unmount — strips `mcpServers.keisei` from every client's config, deletes marker | +| `keisei list-adapters` | Tabular status of every adapter: name / detected / config path | +| `keisei status` | Show currently-attached brain, client list, health (does `mcp_server` binary still exist?) | + +Use cases: + +- **Laptop travel.** Brain lives on USB / iCloud Drive. Plug in at home → `keisei mount /Volumes/MyBrain` attaches to Claude Code + Cursor simultaneously. Unplug → `keisei detach` clears everything. +- **Team shared persona library.** Commit a brain repo to your private Forgejo/GitHub. Every developer clones it, runs `keisei mount ./team-brain`, same 30-agent persona library active in their Claude Code. +- **Cloud brain.** Point `keisei attach s3://my-bucket/brain/` at an S3-backed brain synced via `kei-store` (v0.20 — S3 backend currently MVP stub). Memory follows you to any machine with network. +- **Experimental personas in isolation.** Spin up a test brain via `cp -r ~/production-brain ~/experimental-brain`, `keisei attach ~/experimental-brain`. Iterate without touching production state. + +Security hardening (v0.19.0): + +- Brain `mcp_server` path **must be relative + inside the brain root** (rejects `/usr/bin/curl`, `../../etc/shadow`, `..\..\..\System32\`) +- Brain `name` validated against `^[a-z][a-z0-9_-]{0,63}$` regex +- Brain root rejected if it's a symlink (prevents USB → `$HOME` pivot) +- Adapters **refuse to clobber** existing `mcpServers.` entries — you get an explicit `NameConflict` error, not silent overwrite +- All config writes go through `fsx::write_atomic_json` (Windows-safe via `tempfile::NamedTempFile::persist`) + +Known deferred to v0.19.1: supply-chain hardening (commit `bun.lock`, SHA-pin GitHub Actions), marker file perms 0600, terminal-escape sanitization in status output, manifest size bound. + ## Runtime hook controls Every kit-shipped hook (v0.14.2+) honours two env vars so you can silence noise or isolate a failure without editing `~/.claude/settings.json`: