docs(readme): expand intro — at-a-glance + what-it-solves + keisei CLI section
Prior README went from personal preface ('From the author') directly
into technical inventory ('What it is'). Reader gap: no value
proposition, no capability summary, no exobrain workflow docs.
Added:
- 'At a glance' — 6-bullet capability summary (agents, hooks,
skills, Rust primitives, exobrain, sleep-sync) written so a
stranger arriving from search gets the model in 30 seconds
- 'What it solves' — 7-row table mapping vanilla-Claude-Code pain
points → specific kit component that addresses each
- 'The keisei CLI' — new subsection documenting attach/mount/
detach/list-adapters/status subcommands with brain-directory
layout, 4 use cases (USB travel / team personas / cloud brain /
experimental isolation), security hardening summary, deferred
v0.19.1 items
Counts markers unchanged — no regen needed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Parfii-bot
parent
3ad64332bc
commit
3db30a7084
1 changed files with 72 additions and 0 deletions
72
README.md
72
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 <path>` or `keisei mount <path>` (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, <!-- count:HOOKS -->10<!-- /count:HOOKS --> pre-wired PreToolUse/PostToolUse hooks (three of them dedicated to RULE 0.14 session self-audit), <!-- count:SKILLS -->39<!-- /count:SKILLS --> portable skills (including an interactive `/new-agent` wizard, 10 hub-and-spoke pipelines, and the `/self-audit` retrospective skill), **<!-- count:RUST_CRATES -->25<!-- /count:RUST_CRATES --> Rust primitive crates**, <!-- count:SHELL_PRIMITIVES -->13<!-- /count:SHELL_PRIMITIVES --> opt-in shell primitives (plus 3 always-copied sleep-sync helpers), and <!-- count:BRIDGES -->11<!-- /count:BRIDGES --> 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 `<name>.sha256` for integrity verification. Build det
|
|||
|
||||
If you drop the binary at `~/.claude/agents/_primitives/_rust/target/release/kei-mcp-server-<os>-<arch>[.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:
|
||||
|
||||
```
|
||||
<brain-root>/
|
||||
├── 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 <brain-path> [--client=X]` | Mount brain into a single detected client (default: first detected) |
|
||||
| `keisei mount <brain-path>` | 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.<name>` 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`:
|
||||
|
|
|
|||
Loading…
Reference in a new issue