ce9ba61ee0
README down from 89 KB to 7.8 KB (11x reduction, target was 10-15 KB). Visitor-facing README now loads in one screen — hero + 3 killer features + what-it-solves + quick install + docs index. Extracted 6 new files under docs/: - INSTALL.md (15 KB) — prerequisites, profiles, interactive install, MCP binary, keisei CLI intro, runtime hook controls, what-you-get table - REFERENCE.md (35 KB) — every one of 25 Rust primitives + 13 shell primitives + 10 hooks + 39 skills with actual CLI surface (clap flags, exit codes, env vars, state paths), keisei CLI deep-dive, 12 pipelines - ARCHITECTURE.md (11 KB) — build pipeline, creating-a-new-agent, adding custom blocks/manifests, agents overview, cross-tool bridges, meta-composer, regen counts, workflow-file editing protocol - SLEEP-LAYER.md (11 KB) — three-phase nightly cycle diagram, session self-audit (RULE 0.14), Cloud REM sync, sleep-on-it incubation, deep-sleep NREM consolidation with 4-primitive pipeline + example - SECURITY.md (7.6 KB) — threat surface table + 8 mitigations in detail (memory-repo privacy, secrets-guard patterns, supply-chain SHA pinning, S3 SSRF, brain path/name validation, exFAT warning, battle matrix) - WHY.md (3.6 KB) — full 'From the author' manifesto restored from git history (pre-1f3aaca product pivot). Medium/dev.to-friendly for virality, separate from the product README New docs cross-link each other + README has docs index in tail. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
7.7 KiB
KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code
A structural layer over Claude Code, Cursor, Continue, and Zed that catches the failure modes LLMs introduce at commit time — not after they ship.
Drop-in toolkit: portable agent personas, tool-use hooks that refuse known-bad actions, click-through skill wizards, a Rust primitive library for the tasks Python ships wrongly, and a portable "brain" directory (USB / git / S3) that mounts into any MCP-capable client via one command.
Why it exists
LLMs are statistically wired to produce plausible-but-wrong output. Context windows drop prior decisions, confident citations turn out to be fabricated, parallel terminals clobber each other's files, the same mistake lands on the third try because the retrospective from the first never reached the second session. None of that is solvable by better prompts — it is solvable by structure around the prompt.
KeiSeiKit is that structure: persistent agent memory across sessions, pre-commit hooks at every tool boundary, typed handoff artifacts between agents, a deterministic manifest-to-agent build, and a three-phase overnight consolidation via a cloud cron. Constructor Pattern throughout — one file per concern, every abstraction replaceable.
Rust-first by design. Type-system guarantees remove entire classes of hallucination at compile time: no None-vs-[] confusions, no missing .await, no unhandled Result. For LLM-authored code this is survival, not style. The full philosophical backstory lives in docs/WHY.md.
Three killer features
1. The nightly cycle
Day session → overnight consolidation → morning report. Three phases on an Anthropic-cloud agent mirror biological sleep:
- Phase A — Incubation ("sleep on it"): you defer a hard question via
/sleep-on-it; the remote agent processes it during the night (15 min / 60 min / 4 h / full-night marathon). - Phase B — REM: the agent reads your day's trace JSONL, extracts cross-session patterns, commits
reports/sleep-YYYY-MM-DD.mdback to your private memory-repo. - Phase C — NREM: every 7 days (by default), scans
_rules/+hooks/+_blocks/+memory/for conflicts (duplicate matchers, orphan wikilinks, CP violations) and emits a structured refactor plan.
Morning git pull — you read, you decide. Nothing is auto-injected into a future session. Full mechanics: docs/SLEEP-LAYER.md.
2. Constructor-Pattern agent kit
Agents are built deterministically from TOML manifests + reusable Markdown blocks. Edit a block, the assemble-agents hook rebuilds every affected agent. Ship the same kei-critic persona to every machine by installing the kit. 12 ready agents (kei-code-implementer, kei-critic, kei-validator, kei-security-auditor, kei-architect, kei-researcher, kei-ml-implementer, ...) — all namespaced under kei-* so they won't collide with your own. Full wiring: docs/ARCHITECTURE.md.
3. Exobrain — one brain, every client
Portable brain directory (memory + artifacts + manifests + per-platform MCP server binaries) that mounts into Claude Code, Cursor, Continue, and Zed via a single command. USB stick, iCloud, S3 / R2 / MinIO — same state follows you.
keisei mount /Volumes/MyBrain # attaches to every detected AI client
keisei detach # clean unmount from all clients
Setup path: docs/INSTALL.md § keisei CLI.
What it solves (vs vanilla Claude Code)
| Problem you hit | 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.
Quick install
Two paths, pick what fits your Claude Code version:
# Plugin (recommended on Claude Code 2.1+, zero cargo build)
/plugin marketplace add KeiSei84/KeiSeiKit
/plugin install keisei@keisei-marketplace
# OR classic (required for Rust primitives)
git clone <your-fork-of-this-repo> KeiSeiKit
cd KeiSeiKit
./install.sh # minimal profile, ~5s, no primitives
./install.sh --profile=full # everything, ~5 min, ~200 MB
Plugin vs classic install, profiles (minimal / core / frontend / ops / dev / full), MCP-server pre-built binaries, and runtime hook controls → docs/INSTALL.md.
What's in the box
| Category | Count |
|---|---|
| Behavioral blocks | 79 |
| Generic agents (manifests) | 12 |
| Hooks (PreToolUse / PostToolUse) | 10 |
| Portable skills | 39 |
| Rust primitives (opt-in, profile-gated) | 25 |
| Shell primitives (opt-in) | 13 |
| Cross-tool bridges | 11 |
Every primitive / hook / skill with its actual CLI surface → docs/REFERENCE.md.
Docs
| File | What's in it |
|---|---|
| docs/INSTALL.md | Install paths, profiles, MCP binary, keisei CLI, runtime hook controls |
| docs/REFERENCE.md | Every primitive / hook / skill / pipeline with flags + exit codes |
| docs/ARCHITECTURE.md | Build pipeline, cross-tool bridges, meta-composer, workflow editing |
| docs/SLEEP-LAYER.md | Three-phase nightly cycle + session self-audit |
| docs/SECURITY.md | Threat model + mitigations |
| docs/WHY.md | Full "From the author" philosophical backstory |
| docs/USB-BRAIN-GUIDE.md | Portable brain on removable media — macOS / Linux / Windows splits |
| CHANGELOG.md | Release notes (Conventional Commits → Markdown via kei-changelog) |
| PLUGIN.md | Anthropic plugin-format install path (v0.16+) |
About
Built by Denis Parfionovich (parfionovich@keilab.io) as a personal working environment — not a commercial product. The problems it solves are ones I hit every day across 4–8 parallel Claude Code terminals.
Most of what is here is well-established bricks (git-as-state, cron, TF-IDF, Constructor-Pattern composition). What may be new in the Claude Code context is the Constructor Pattern for agents (composable blocks, deterministic build, rebuild-on-block-edit hooks) and the three-phase sleep layer (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly incubation + REM + NREM consolidation).
Treat this as my sample, not a claim of originality. Forks and PRs welcome from everyone, not only from those who write code. Open an issue at github.com/KeiSei84/KeiSeiKit/issues — a well-formulated problem is already half the solution. Full backstory in docs/WHY.md.
License
MIT. See LICENSE.