KeiSeiKit-1.0/README.md

KeiSeiKit — Constructor-Pattern Agent Kit for Claude Code

From the author

Hello.

Transformers are statistically wired to lie. It is not a bug, it is the core operation: they pick the next token by sampling a probability distribution conditioned on whatever context happens to fit the window. They cannot reliably hold long context, they will drag a hallucination picked up three thousand tokens ago into a confident final sentence, and they may deliver a brilliant insight right next to a fabricated citation. This is not fixable inside the model — it is mathematically baked in from the moment of tokenization onward.

This kit is my humble attempt to build scaffolding around those errors. Not to fix the transformer, but to make it behave a little closer to my own working logic: catch the common failure modes before they reach a commit, give it external memory that survives session boundaries, give it a rhythm resembling human work (day sessions → overnight consolidation → morning report), and let parallel agents coordinate through a shared state instead of stepping on each other.

I work across 4 to 8 parallel Claude terminals most days. The problems I hit are mundane: forgetting between sessions, repeating the same mistake on the third try, parallel agents clobbering each other's files, a hallucinated API name shipped to production. None of these are solvable by a better prompt. They are solvable by structure around the prompt.

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 sleep-sync (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly REM-style consolidation).

Why Rust, not Python. Transformers write Python confidently and wrongly. Five minutes to a plausible-looking function, two hours to debug why dict.get("key", None) or [] silently swallowed an empty list, or why an async context manager leaked a file handle across a retry loop. Rust's type system catches whole categories of those errors at compile-time — the model literally cannot ship a None-vs-[] confusion, a missing .await, or an unhandled Result, because the compiler refuses. For an LLM-written codebase this is not aesthetic preference, it is survival. Every Rust primitive here is one category of hallucination the transformer is no longer allowed to commit.

It is not a product. It helps me personally. If it resonates with you, let me know. If enough feedback comes in, there will be a next version — more primitives, more patterns against the "forgetful" transformer. But that needs input; without it, I just keep using this quietly myself.

Forks and PRs welcome from everyone, not only from those who write code. If you hit a problem with Claude Code and have an idea for solving it, open an issue with the description. A well-formulated problem is already half the solution.

Hope it is a small Kei for someone to make vibecoding better.

And double sorry if I'm repeating someone — I never tried other kits, since this one is just all my rules stacked in one place. I can't always tell what I have seen somewhere and what came from my own head — so treat this as just my sample, not a claim of originality.

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

The kit is MIT-licensed and fully generic — install it on a fresh machine and you get a sane 12-agent fleet (implementers, critics, researchers, cost-guardians, and more — all namespaced under kei-* so they won't collide with your own same-named agents), a wizard for spinning up new project specialists, 10 pipeline skills that combine primitives end-to-end (/compose-solution, /site-create, /schema-design, /observability-setup, /auth-setup, /api-design, /ci-scaffold, /test-matrix, /docs-scaffold, /new-project, /vm-provision), and a build pipeline that keeps every agent derivable from its manifest.

Prerequisites

Hard (needed for every install, regardless of profile):

• Rust (stable toolchain) — the assembler Cargo workspace is always built
• jq — used by the shell hooks for JSON parsing (brew install jq / apt install jq)
• Claude Code — the agents, hooks, and skills target Claude Code's agent / skill / hook surface

Soft (only needed if the chosen profile pulls the primitive in — see the profile table below):

• pandoc — tomd uses it for .docx / .pptx / .html (needed for core / full profile)
• Node + Playwright — for the 3 browser-driven frontend primitives design-scrape, live-preview, mock-render (frontend / full profile); install with npm i -g playwright && playwright install chromium
• sqlite3 CLI — optional for manual DB inspection of kei-ledger / kei-migrate (their binaries embed SQLite via rusqlite; ops / dev profile)
• hcloud / vultr-cli — wrapped by provision-hetzner / provision-vultr (ops profile)
• yq v4 (mikefarah/yq Go impl) — required by kei-ci-lint (dev profile)

install.sh checks only the deps relevant to the selected profile and soft-warns once per missing tool.

Install

git clone <your-fork-of-this-repo> KeiSeiKit
cd KeiSeiKit
./install.sh                      # profile=minimal (default, no primitives)

install.sh is idempotent. It:

1. Creates ~/.claude/agents/{_blocks,_manifests,_primitives,_bridges,_templates,_assembler,_generated}, ~/.claude/hooks, ~/.claude/skills
2. Copies all blocks + bridges (overwrites — these are SSoT from the kit)
3. Copies primitives ONLY for the selected profile (default: minimal = none). Tracks installed set in ~/.claude/agents/_primitives/.installed.
4. Copies generic manifests (skips if you already have a manifest with that name)
5. Builds the Rust assembler (cargo build --release in _assembler/)
6. If any Rust primitive is in the selected profile: writes a scoped workspace Cargo.toml listing ONLY the installed crates, then cargo build --release
7. Generates agent .md files in-place with AGENT_ROOT=~/.claude/agents assemble --in-place
8. Copies the 10 hooks and 39 skills

After install, the only remaining step is merging settings-snippet.json into your ~/.claude/settings.json to activate the hooks. You can do this automatically with ./install.sh --activate-hooks or answer y at the end-of-install TTY prompt.

Interactive install

Run ./install.sh with no profile flag on a TTY and you get a menu:

• whiptail or dialog detected → curses-style TUI (radiolist for profile, checklist for custom)
• neither available → plain-text numbered picker (1-7 + a custom option)

After the profile is chosen, an Install Plan screen summarizes what will be copied, which soft-deps are present (jq, pandoc, playwright, cargo, hcloud, vultr-cli, yq, sqlite3, curl), and the rough time + disk footprint — then asks Proceed? [Y/n]. Pass --yes to skip the confirm screen (the menu still runs). Pass --no-execute to parse menu + confirm and exit without copying anything (useful for dry-run). The menu is skipped automatically when any selection flag is passed (--profile, --add, --remove, --list) or when stdin/stdout is not a TTY (CI runs default to minimal exactly as before).

Install profiles

By default ./install.sh is minimal — agents + hooks + skills + bridges, no primitives. Fastest (~5s) and zero Rust compile for primitives. You opt into primitives via --profile=<name> or one-at-a-time via --add=<name>.

Profile	Primitives added	Install time	Disk (approx)
minimal (default)	none	~5s	~2 MB
core	tomd	~5s	~2 MB
frontend	8 site tools: mock-render, visual-diff, tokens-sync, design-scrape, live-preview, figma-tokens, frontend-inspect, screenshot-decode	~60s	~80 MB
ops	8 infra tools: kei-ledger, ssh-check, firewall-diff, provision-hetzner, provision-vultr, harden-base, metrics-scrape, log-ship	~90s	~50 MB
dev	10 dev tools: kei-migrate, kei-changelog, kei-ci-lint, kei-docs-scaffold, kei-memory, kei-conflict-scan, kei-refactor-engine, kei-graph-check, kei-store, kei-artifact	~60s	~40 MB
full	everything (38 primitives)	~5 min	~200 MB

Examples:

./install.sh                        # minimal (no primitives)
./install.sh --profile=frontend     # minimal + <!-- count:PROFILE_FRONTEND -->8<!-- /count:PROFILE_FRONTEND --> site tools
./install.sh --profile=full         # everything (old default behaviour)
./install.sh --add=kei-ledger       # add a single primitive on top of current install
./install.sh --add=kei-ledger,ssh-check
./install.sh --add=ops              # a profile name works too — unions its members in
./install.sh --list                 # show each primitive: name | kind | installed? | description
./install.sh --remove=kei-migrate   # remove one (rebuilds scoped rust workspace if needed)

Profile resolution lives in _primitives/MANIFEST.toml — one [primitive.<name>] entry per primitive plus a [profile] block. Edit the manifest to define new profiles without touching install.sh.

Migrating from a full install: if you're re-running install.sh after an earlier version that installed all primitives unconditionally, the new default (minimal) will REMOVE them. To preserve the old behaviour explicitly, pass --profile=full (currently 38 primitives).

Re-install disclaimer: install.sh is idempotent for clean state but overwrites kit-owned _blocks/, _primitives/, _bridges/, _templates/, _assembler/, hooks/, and skills/ on re-run — local modifications under those directories are backed up to <dir>.bak-TIMESTAMP/ (or, for shared hook files, to <file>.bak-TIMESTAMP). User-owned _manifests/*.toml are never overwritten.

MCP server binary (zero-install path, v0.18)

From v0.18 each GitHub release ships a single static binary of the @keisei/mcp-server package for five platforms — no Node, no npm install. Drop the binary anywhere (USB stick, S3 bucket, Downloads folder) and run it. This is Phase 1 of the "exobrain" distribution goal: any MCP-capable client can mount KeiSeiKit from read-only media.

Platform	Asset name
Linux x64	kei-mcp-server-linux-x64
Linux arm64	kei-mcp-server-linux-arm64
macOS x64	kei-mcp-server-darwin-x64
macOS arm64	kei-mcp-server-darwin-arm64
Windows x64	kei-mcp-server-windows-x64.exe

# Linux / macOS
curl -L -o kei-mcp-server \
  https://github.com/<your-fork>/KeiSeiKit/releases/latest/download/kei-mcp-server-darwin-arm64
chmod +x kei-mcp-server
# macOS only — clear Gatekeeper quarantine on the downloaded binary:
xattr -d com.apple.quarantine ./kei-mcp-server 2>/dev/null || true
./kei-mcp-server --stdio

Every asset has a matching <name>.sha256 for integrity verification. Build details and local cross-compile recipes: _ts_packages/packages/mcp-server/BUILD.md.

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-darwin-x64
    ├── kei-mcp-server-linux-x64
    ├── kei-mcp-server-linux-arm64
    └── kei-mcp-server-windows-x64.exe

manifest.toml — schema v2 (recommended, v0.20+) dispatches to the right binary for the host at attach time:

[brain]
schema_version = 2
name = "my-brain"
created = "2026-04-22T00:00:00Z"

[paths.mcp_server]
darwin-arm64  = "bin/kei-mcp-server-darwin-arm64"
darwin-x64    = "bin/kei-mcp-server-darwin-x64"
linux-x64     = "bin/kei-mcp-server-linux-x64"
linux-arm64   = "bin/kei-mcp-server-linux-arm64"
windows-x64   = "bin/kei-mcp-server-windows-x64.exe"

A single brain on USB/iCloud now serves every host automatically. Schema v1 (single-string mcp_server = "bin/...") is still accepted for backward-compat.

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.21 — real S3 / R2 / MinIO backend behind the s3 feature flag). 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:

• KEI_DISABLED_HOOKS — comma- or space-list of hook base names (no .sh), e.g. KEI_DISABLED_HOOKS=site-wysiwyd-check,milestone-commit-hook. The literal all disables every hook.
• KEI_HOOK_PROFILE — one of full (default), advisory-off, minimal, off.

Profile	What stays on
full (default)	Every hook
advisory-off	Disables pure-stderr advisories (recurrence-suggest, citation-verify, error-spike-detector, milestone-commit-hook). Safety gates stay on.
minimal	Only safety-critical: no-github-push, genesis-leak-guard, no-hand-edit-agents, secrets-guard, assemble-validate, git-pre-commit-genesis. Everything else off.
off	Every hook off — escape hatch for debugging hook interactions.

# One-session disable of a single noisy hook:
export KEI_DISABLED_HOOKS=site-wysiwyd-check

# Permanent quieter profile (paste into ~/.zshrc / ~/.bashrc):
export KEI_HOOK_PROFILE=advisory-off

# Full re-enable:
unset KEI_DISABLED_HOOKS KEI_HOOK_PROFILE

Interactive wizard: run /hooks-control — click-only picker that shows current state and emits the export / unset command for you to paste. The skill never executes anything itself.

What you get

Category	Count	Examples
Behavioral blocks	79	baseline, evidence-grading, rule-math-first, stack-rust-axum, stack-react-vite, stack-sveltekit, stack-astro, deploy-modal, api-fal-ai, ...
Generic agents (manifests)	12	kei-code-implementer, kei-critic, kei-validator, kei-security-auditor, kei-architect, kei-researcher, kei-ml-implementer, kei-cost-guardian, kei-modal-runner, ...
Hooks (PreToolUse / PostToolUse)	10	assemble-agents, assemble-validate, no-hand-edit-agents, tomd-preread, agent-fork-logger, orchestrator-dirty-check, site-wysiwyd-check, session-end-dump, milestone-commit-hook, error-spike-detector
Portable skills	39	compose-solution, new-agent, new-project, site-create, schema-design, observability-setup, auth-setup, api-design, ci-scaffold, test-matrix, docs-scaffold, vm-provision, ...
Primitives (Rust crates, opt-in)	25	kei-ledger, kei-migrate, kei-changelog, ssh-check, firewall-diff, mock-render, visual-diff, tokens-sync, kei-memory, kei-conflict-scan, kei-refactor-engine, kei-graph-check, kei-store, kei-router, kei-sage, kei-task, kei-chat-store, kei-crossdomain, kei-search-core, kei-content-store, kei-social-store, kei-curator, kei-auth
Primitives (shell, opt-in via profile)	13	tomd, design-scrape, live-preview, figma-tokens, frontend-inspect, screenshot-decode, metrics-scrape, log-ship, provision-hetzner, provision-vultr, harden-base, kei-ci-lint, kei-docs-scaffold
Shell helpers (always copied)	3	kei-sleep-setup, kei-sleep-sync, kei-sleep-queue (dormant until you run /sleep-setup)
Cross-tool bridges	11	Cursor legacy/MDC, Codex, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit

Of the 79 blocks, the 8 base blocks (baseline, evidence-grading, memory-protocol, rule-pre-dev-gate, rule-test-first, rule-error-budget, rule-double-audit, rule-math-first) are referenced directly by the 12 shipped manifests. The remaining blocks (stack-*, deploy-*, api-*, scraper-*, domain-*) are a library consumed by the /new-agent wizard and the hub-and-spoke pipeline skills: when you compose a project specialist or spin up a site, the wizard / pipeline picks the appropriate blocks and emits artefacts that reference them.

Cognitive mode blocks (_blocks/mode-*.md) are composable behavioural skews — mode-skeptic, mode-devils-advocate, mode-minimalist, mode-maximalist, mode-first-principles. Add any combination to an agent's manifest blocks = [...] list to stack the mode. Modes compose: mode-skeptic + mode-minimalist gives you an adversarial pruner; mode-devils-advocate + mode-first-principles gives a constraint-driven steel-manner. See _blocks/README.md for the full list.

Creating a new agent

Run the wizard in Claude Code:

/new-agent

You'll be asked (via multiple option-picker batches, not free-text) — each batch groups several click-only questions into a single AskUserQuestion call:

1. Project stack (Rust CLI / axum / SwiftUI / Flutter / FastAPI / Next.js / React-Vite / Vue-Nuxt / SvelteKit / Astro / Go / Embedded / Python ML)
2. Deploy target (local-only / EC2 / Cloudflare / Modal / Docker / none)
3. Uses paid APIs? (Yes / No)
4. Contains ML? (Yes / No)
5. Has credentials? (Yes / No)
6. Uses scrapers? (None / Free-tier / Paid tier)

Then one free-text prompt for slug + description + path + gotchas. The wizard composes the manifest, validates it, assembles the .md, and prints a two-step git-commit command you can run or edit first.

Pipelines

Hub-and-spoke skills that combine primitives into end-to-end flows. Each one is an option-picker-first, free-text-last wizard; every phase has a verify-criterion.

Skill	One-line purpose
/compose-solution	Meta-composer: decompose any task, grep prior art, propose math-first architecture, assemble the right artefact (agent / skill / hook / block)
/new-project	Bootstrap a project specialist agent + repo skeleton + bridges + ledger row
/new-agent	Interactive 6-question wizard that builds a project-specialist manifest and its .md
/site-create	Frontend stack pick → design tokens → scaffold → WYSIWYD loop (mock-render, visual-diff, tokens-sync)
/schema-design	DB schema design → migrations → kei-migrate apply (PG/SQLite/MySQL autodetect)
/observability-setup	Pick metrics + logs stack → scrape + ship config (metrics-scrape, log-ship)
/auth-setup	Pick auth model (session / JWT / OAuth2) → emit routes + middleware + token rotation
/api-design	Contract-first: pick REST vs GraphQL vs gRPC, emit types + handlers + tests
/ci-scaffold	GitHub Actions / Forgejo Actions workflow skeleton + kei-ci-lint pre-commit
/test-matrix	Test stack matrix: unit / integration / e2e / visual; pick stack, emit skeleton
/docs-scaffold	Doc site skeleton (mdbook / docusaurus / astro-starlight) + kei-changelog generator
/vm-provision	VM provider pick → provision-* primitive → harden-base + ssh-check + firewall-diff verification

All pipelines share a single discovery layer: /compose-solution Phase 3's prior-art grep covers _blocks/, _manifests/, _primitives/ (shell + Rust), skills/, _bridges/, hooks/ — so any pipeline can reuse primitives without re-inventing them.

Session self-audit (RULE 0.14)

KeiSeiKit auto-analyzes sessions on 3 triggers:

• Stop event — session ended; session-end-dump.sh archives the JSONL trace and ingests it into kei-memory.
• Milestone commits — git commit -m "feat:" / "refactor:" / git merge; milestone-commit-hook.sh appends a one-line session summary to ~/.claude/memory/audit-backlog.md.
• Error spike — 3+ errors in the last 20 tool calls; error-spike-detector.sh tags the pattern and logs it.

Findings surface via click-only AskUserQuestion, routing to /escalate-recurrence (codify rule + wiki + hook), /debug-deep (5-phase RCA), or the audit backlog (log-only). Silent-first: the first 10 sessions log only — prompts activate from session 11 onward so the memory store has a useful baseline before it interrupts you. Counter lives in ~/.claude/memory/audit-backlog.md as <!-- session_count: N -->.

Manual trigger: /self-audit skill (same flow, invoked on demand).

Requires the kei-memory primitive. Included in the dev and full profiles; otherwise add via ./install.sh --add=kei-memory.

Cloud REM sync (sleep layer, v0.11.0)

Run a nightly "sleep" cycle on Anthropic's cloud — no laptop, no infra, no DevOps.

How it works:

• Each session: your Mac pushes trace JSONL to a private git repo you control
• 03:00 local time: a remote Claude Code agent clones the repo, analyzes the last 24h of traces, writes reports/sleep-YYYY-MM-DD.md, and commits back
• Next morning: git pull and read the consolidated findings

Setup (one-time, ~5 min):

1. Create an empty private repo on GitHub / GitLab / Bitbucket / self-hosted Forgejo
2. In Claude Code run /sleep-setup
3. The wizard generates an SSH deploy key → you paste it into the repo's deploy-key settings with WRITE access
4. The wizard emits a ready-to-paste /schedule create command, converted to your local 03:00 in UTC

After that, the sleep cycle runs every night automatically. The morning report is yours to read — nothing is auto-injected back into any session.

Requires the kei-memory primitive (shipped in the dev and full profiles; add via ./install.sh --add=kei-memory otherwise). Sleep-sync scripts themselves are installed unconditionally and stay dormant until you opt in via /sleep-setup.

Opt in at install time with ./install.sh --with-sleep-sync (TTY-only). Governed by RULE 0.15 in ~/.claude/rules/sleep-layer.md.

Sleep on it (incubation, v0.12.0)

Defer a hard question or research task to the nightly remote agent: run /sleep-on-it, fill in one free-text field plus three clicks (type / priority / format), submit. The task lands in sync-repo/sleep-queue/ and the nightly agent processes it before REM consolidation.

Priority maps to a wall-clock budget. Pick the one that matches the task's difficulty:

Priority	Budget	When to pick
Quick	15 min, this night	Simple questions, fast lookups
Standard	60 min, this night	Default, medium research
Deep	4 hours, this night	Serious derivations, thorough prior-art
Marathon	Full night (up to 8 h), 1 task only	Hard equations, full autonomy; Phase B REM skipped that night
Weekly batch	60 min, next Sunday UTC	Non-urgent research

Checkpointing: Standard / Deep / Marathon runs commit a .partial.md every 20–30 minutes, so if the cloud session is cut short you still get the partial on morning pull.

Typical use:

• "Should I use CfC for memory re-ranker?" → deep-research → architectural recommendation by morning
• "Compare SvelteKit vs Astro vs Next.js App Router for the kit's landing" → comparative study
• "Derive closed form for the CfC attractor on Stiefel V(p,k=2)" → marathon mode, full night of autonomous derivation
• "What patterns in audit-backlog have highest impact?" → pattern analysis

Results in sync-repo/sleep-results/<uuid>.md, linked from the next morning's REM report. Biological analog: the REM-sleep "sleep on it" effect (Wagner et al. 2004, Nature). Queue mutations go through the kei-sleep-queue helper.

Deep-sleep NREM consolidation (v0.13.0)

A third nightly phase — Phase C — runs after REM on a user-chosen cadence (default: every 7 days). Biological analog: NREM slow-wave-sleep system consolidation. The remote agent scans your memory-repo for conflicts across rules, hooks, _blocks/, and memory (contradictory directives, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations) and produces a structured refactor plan.

Two output modes, chosen once in /sleep-setup Phase 3b:

• Plan only (default) — markdown report in sync-repo/sleep-deep/YYYY-MM-DD-plan.md. Read in the morning, decide what to merge by hand.
• Plan + fork — same plan plus an auto-resolve review markdown (YYYY-MM-DD-autoresolve.md) listing the auto-resolvable conflicts with WHY / EXAMPLE / TRADEOFF per item. You open each file in an editor, apply the suggested change, commit on a deep-sleep/YYYY-MM-DD branch, then let the graph-check gate verify the wikilinks still resolve.

v0.14.1 retraction: earlier README claimed a git apply-ready patch. The engine cannot synthesise real unified-diff hunks without reading the source files — that would risk fabricated edits (RULE 0.4). The autoresolve file is now plain markdown reviewed and applied by hand; the "fork" path only automates the rename/move class of ops, not content edits.

Zero-conflict guarantee: any conflict the engine marks requires_human_decision is EXCLUDED from the auto-resolve markdown and listed plainly in the plan. No silent auto-apply of ambiguous changes.

Store backends (picked in Phase 3b, consumed via the new kei-store trait):

Backend	Status	Notes
GitHub private	production	SSH deploy key or PAT; default
Forgejo self-hosted	production	Same wire protocol as GitHub
Gitea self-hosted	production	Same wire protocol
Filesystem only	production	Local .git; no push; fastest
S3 / R2 / MinIO	production (v0.21, behind s3 feature)	Real GetObject / PutObject / ListObjectsV2 via aws-sdk-s3. Build with cargo build -p kei-store --features s3 and set [s3] bucket = "..." in store-config.toml. AWS default credential chain (env vars → ~/.aws/credentials → IMDS). Custom endpoint for R2 / MinIO / Wasabi via KEI_STORE_S3_ENDPOINT env or s3.endpoint TOML field. Binary grows ~5 MB when the feature is on. Omit the feature OR omit s3.bucket to fall back to the v0.14 local-manifest stub (still gated by KEI_STORE_ALLOW_S3_STUB=1).

Requires the new kei-conflict-scan, kei-refactor-engine, kei-graph-check, and kei-store primitives (shipped in the dev and full profiles). Governed by the Phase C extension of RULE 0.15 in ~/.claude/rules/sleep-layer.md.

Primitives (Rust)

_primitives/_rust/ is a Cargo workspace with 25 single-binary crates (v0.13.0 added 4 deep-sleep primitives; v0.14.0 added 10 LBM-port MCP crates; v0.14.2 removed genesis-scan — internal-only tool, not shipped publicly). install.sh builds --release for the subset selected by the active profile and drops binaries at ~/.claude/agents/_primitives/_rust/target/release/<name>.

Crate	Purpose
kei-ledger	Agent-fork lifecycle SQLite (fork / done / fail); SSoT for RULE 0.12
kei-migrate	Universal DB migration runner — Postgres / SQLite / MySQL autodetect from DATABASE_URL
kei-changelog	Git-cliff-style CHANGELOG.md generator from Conventional Commits
ssh-check	sshd_config linter — flags weak ciphers, PermitRootLogin yes, password auth, etc.
firewall-diff	ufw intended-vs-running diff — catches drift between declared policy and live kernel rules
mock-render	Playwright wrapper — takes screenshots with SHA-locked PNGs (WYSIWYD: What You See Is What You Deploy)
visual-diff	Pixel diff with tolerance — used in /site-create screenshot-regression loop
tokens-sync	Design tokens JSON → Tailwind config extend + CSS variables under :root
kei-memory	Session retrospective + recurring pattern detector; offline-first analyzer powering RULE 0.14 self-audit
kei-conflict-scan	v0.13.0 — deep-sleep conflict scanner across rules/hooks/blocks/orphans/CP violations
kei-refactor-engine	v0.13.0 — consumes kei-conflict-scan JSON; emits plan markdown + auto-resolve review markdown (NOT a unified diff; v0.14.1 retraction)
kei-graph-check	v0.13.0 — post-refactor wikilink + handoff + block-ref resolver gate
kei-store	v0.21.0 — memory-repo backend abstraction (GitHub / Forgejo / Gitea / Filesystem / S3). S3 backend is a real aws-sdk-s3 client when built with --features s3 (supports AWS / R2 / MinIO / Wasabi); otherwise falls back to the v0.14 local-manifest stub.
keisei	v0.19.0 — exobrain multi-client CLI — attach / mount / detach / status / list-adapters. Mounts a portable brain into every detected AI client in one shot. Supported clients: Claude Code, Cursor, Continue, Zed. mount fan-outs to all detected adapters; detach round-trips cleanly and preserves the user's other MCP/context-server entries. Marker SSoT is ~/.claude/keisei-attached.toml (schema v2 — list of attachments; v1 auto-migrated).

Primitives (shell)

_primitives/*.sh is the shell-primitive layer. Installed at ~/.claude/agents/_primitives/ by install.sh with chmod +x.

Primitive	Purpose
tomd	Universal non-native-format → markdown (PDF, DOCX, XLSX, PPTX, CSV, images with OCR, code)
design-scrape	Scrape a live URL's DOM + computed styles + asset manifest into a structured JSON blob
live-preview	start / stop / status dev server wrapper — writes .keisei/dev-server.pid for hook discovery
figma-tokens	Figma API → design tokens JSON (consumed by tokens-sync)
frontend-inspect	Pointer a running dev server, dump DOM tree + accessibility tree + CSS cascade for a given selector
screenshot-decode	OCR + layout extraction from a screenshot (used when design source is a PNG, not code)
metrics-scrape	Pull Prometheus / OpenMetrics endpoints, normalize, diff against baseline
log-ship	Tail structured logs, forward to Loki / CloudWatch / journald with rate limits
provision-hetzner	Hetzner Cloud API provisioner — server create + cloud-init + ready-wait
provision-vultr	Vultr API provisioner — same shape as Hetzner
harden-base	Post-provision baseline hardening — fail2ban, ufw, unattended-upgrades, no-root-ssh
kei-ci-lint	Pre-commit / pre-push CI lint — runs the minimum-viable checks locally before push
kei-docs-scaffold	One-shot doc site skeleton emitter (mdbook / docusaurus / astro-starlight)

Architecture

  Manifest (_manifests/<name>.toml)          <-- source of truth
         |
         |   [assembler/src/*.rs]              <-- Rust binary
         v
  Generated agent (.claude/agents/<name>.md)  <-- regenerated, never hand-edited
         ^
         |                                     [hook: assemble-agents]
  Block edit (_blocks/<block>.md)             <-- triggers rebuild of ALL agents

10 hooks enforce the pipeline (6 pipeline + 3 session-audit):

• assemble-agents (PostToolUse, Write/Edit) — rebuilds the affected agent(s) whenever a manifest or a block changes. No manual rebuild needed.
• assemble-validate (PreToolUse, Bash) — blocks git commit inside ~/.claude if any manifest fails validation. Keeps the repo in a buildable state at all times.
• no-hand-edit-agents (PreToolUse, Edit/Write) — refuses edits to any .md under ~/.claude/agents/ that starts with the <!-- GENERATED --> marker, pointing you at the manifest instead. Override with AGENT_MIGRATION=1 for emergencies only.
• tomd-preread (PreToolUse, Read) — auto-converts opaque binary formats (.docx, .doc, .xlsx, .pptx, .csv) to markdown via the tomd primitive and redirects Claude to read the cached .md instead.
• agent-fork-logger (PreToolUse, Agent) — RULE 0.12 advisory: logs every Agent subagent invocation to the kei-ledger SQLite DB so the orchestrator can validate the fork bundle. Never blocks; silent no-op if kei-ledger is absent.
• orchestrator-dirty-check (PreToolUse, Agent) — RULE 0.13 advisory: stderr-warns when git status --porcelain of the current repo is non-empty before spawning a sub-agent, so orchestrators don't compound uncommitted output across parallel agents. Never blocks; bypass with ORCHESTRATOR_DIRTY_OK=1 (per-call) or ORCHESTRATOR_META=1 (meta-orchestrator).
• site-wysiwyd-check (PostToolUse, Edit/Write) — on frontend-source edits (.tsx, .vue, .svelte, .astro, .css, .html, .jsx, .ts) in a project with a live dev server (.keisei/dev-server.pid), takes a Playwright screenshot via mock-render and diffs against .keisei/target.png via visual-diff. Advisory-only — drift is reported to stderr, never blocks.
• session-end-dump (Stop event) — RULE 0.14 self-audit: archives the session JSONL trace and ingests it into kei-memory.
• milestone-commit-hook (PostToolUse, Bash) — RULE 0.14 self-audit: appends a one-line session summary to ~/.claude/memory/audit-backlog.md on every feat:/refactor:/merge commit.
• error-spike-detector (PostToolUse, any tool) — RULE 0.14 self-audit: tags + logs the pattern when 3+ errors occur within the last 20 tool calls.

Regenerating counts

Every number above (crates / skills / hooks / blocks / primitives / profile sizes) is wrapped in an HTML-comment marker — <!-- count:NAME -->24<!-- /count:NAME --> — and regenerated from sources of truth (_primitives/MANIFEST.toml, _primitives/_rust/Cargo.toml, filesystem walks). No more drift when a primitive or skill is added.

./scripts/regen-counts.sh            # rewrite README.md in place
./scripts/regen-counts.sh --check    # exit 1 if drift detected (no writes)

Pre-commit gate: scripts/precommit-counts-check.sh — wire it into your hook manager (or symlink into .git/hooks/pre-commit) to block commits when README counts drift from the sources.

Workflow-file editing protocol

Every .github/workflows/*.yml edit is defended by three gates. The v0.20.1 incident (a real-but-wrong-semantic SHA pin on dtolnay/rust-toolchain broke CI for 30 minutes before discovery) motivated formalising them.

• scripts/lint-workflows.sh — runs actionlint over every workflow file. Catches syntax errors, expression typos, dead if: branches, and shell-injection risks. If the binary isn't on PATH, the script prints an install hint and exits 0 (advisory). Install with bash scripts/install-actionlint.sh or brew install actionlint.
• scripts/validate-workflow-shas.sh — extracts every uses: <repo>@<sha40> pin from .github/workflows/*.yml + .github/dependabot.yml and runs git ls-remote https://github.com/<repo>.git <sha>. A fabricated or force-pushed-out-of-existence SHA exits 1 with SHA MISSING:. Network errors are soft ([UNVERIFIED]). Tag refs like @v4 or @stable are skipped (policy decision). Add trailing comment # validate-workflow-shas: skip=<reason> on a line to intentionally skip it.
• CI job workflow-lint — runs both scripts on every push and PR. Finishes in well under 30 s.
• Optional pre-commit hook: ln -sf ../../scripts/pre-commit-workflow-lint.sh .git/hooks/pre-commit — runs the two scripts only when a workflow file is staged.

SHA-pinning third-party actions defeats tag re-point attacks (CVE-2025-30066 class), but only if the SHA you wrote is real AND means what you think it means. actionlint catches the first class of mistake; validate-workflow-shas.sh catches the second. Together they close the window between local edit and CI-fail.

Adding custom blocks

Blocks are plain markdown in ~/.claude/agents/_blocks/. To add one:

1. touch ~/.claude/agents/_blocks/stack-mystack.md and write the block.
2. Reference it in a manifest's blocks = [...] list.
3. The PostToolUse hook rebuilds the affected agent(s) automatically.

Blocks should be 10-50 lines, single-concern, and readable in isolation. If a block exceeds ~60 lines, split it into two.

Adding custom manifests

Copy _templates/specialist.toml.template and fill the placeholders, OR run /new-agent and answer the wizard. Either way, the assembler validates the manifest and generates the .md on write.

Agents overview

All kit agents are namespaced under kei-* so they won't collide with your own agents (e.g. your personal validator or critic) living in ~/.claude/agents/.

Agent	Role
kei-code-implementer	Write production code, Constructor Pattern enforced, Test-First discipline
kei-infra-implementer	Deploy scripts, CI/CD, secrets management, cost-aware paid infra
kei-ml-implementer	Training scripts, inference code, Modal jobs, exact param counts
kei-critic	Read-only anti-pattern / bug / security / perf / debt finder
kei-validator	Fact-checker; verifies API existence, version compat, citations, doc claims
kei-security-auditor	Risk-classified security audit with variant analysis + supply chain check
kei-architect	Read-only structural analysis; dep graph, patterns, coupling
kei-researcher	Generic web + codebase research, evidence-graded findings
kei-ml-researcher	ML literature, benchmarks, reproducibility, tooling-reuse search
kei-cost-guardian	Pre-launch GO/NO-GO for paid compute (Modal, AWS, fal.ai, Apify, etc.)
kei-modal-runner	Modal compute orchestrator with KILL GUARD (never stops running jobs)
kei-fal-ai-runner	fal.ai image/video/3D generation expert

Cross-tool bridges

KeiSeiKit ships 11 verified tool-bridge templates under _bridges/. Render them into any project and the same Constructor-Pattern ruleset is visible to every AI coding tool you use — no drift, one source of truth.

Tools covered:

Tool	Output file
Cursor (legacy)	.cursorrules
Cursor (modern MDC)	.cursor/rules/main.mdc
Codex CLI / Warp / Zed / Antigravity fallback	AGENTS.md
GitHub Copilot	.github/copilot-instructions.md
Windsurf	.windsurf/rules/main.md
JetBrains Junie	.junie/guidelines.md
Continue.dev	.continue/rules/main.md
Google Antigravity / Gemini CLI	GEMINI.md
Aider	CONVENTIONS.md + .aider.conf.yml
Replit Agent	replit.md

Three ways to generate:

1. At install time — ./install.sh --with-bridges renders all 11 into $PWD after the normal install completes. Skipped if $PWD is the KeiSeiKit repo itself.
2. From the /new-agent wizard — Phase 8 asks click-only whether to generate all 11, just AGENTS.md, or skip.
3. Manually, any time — ~/.claude/agents/_bridges/emit.sh <project-dir> (the install copies _bridges/ into your agent fleet dir). Add --only <output-path> to restrict to a single file.

All paths are idempotent: existing bridge files in the project are skipped, never overwritten. See _bridges/README.md for the full template→output-path table.

Meta-composer

/compose-solution is the meta-creator: tell it what you want to solve in one free-text paragraph, it decomposes the task, greps existing blocks / skills / manifests / primitives / bridges for prior art, proposes a minimal math-first architecture, and assembles the right artefact — agent, skill, hook, rule, block, or pipeline invocation. Every decision except the intake is a click (option-picker), never free-text.

Example: "I want a hook that blocks rm -rf ~/ in any Bash call" → Phase 2 decomposes into (pattern-match, severity, event, wiki entry) → Phase 3 greps hooks/, _blocks/, _primitives/ for prior art → Phase 5 proposes hook = PreToolUse:Bash + pattern + exit 2 → Phase 7 hands off to /escalate-recurrence with severity and event pre-filled.

Phase 6 is the feedback loop: when a component has no prior art, the skill drafts a new _blocks/<slug>.md and — on your click — persists it. Next time /compose-solution (or /new-agent) runs, that block is discoverable. Every session leaves the kit a little smarter; the report prints _blocks/ count before → after so the growth is visible.

See skills/compose-solution/SKILL.md and its phase files (phase-1-intake.md through phase-7-assemble.md) for the full 7-phase pipeline.

License

MIT. See LICENSE in this directory.