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.

Reference

Every shipped component, its real behaviour, and where to look in source. Each subsection documents the actual CLI surface as extracted from _primitives/_rust/*/src/main.rs, _primitives/*.sh, hooks/*.sh, and skills/*/SKILL.md. If a flag or subcommand is not listed here, it does not exist in the current build.

Rust primitives

All 25 crates live under _primitives/_rust/<name>/. After install.sh runs, binaries land at ~/.claude/agents/_primitives/_rust/target/release/<name>. Exit codes: 0 success, 1 usage/IO error, 2 validation/diff-found (per-tool; see each entry).

kei-ledger — agent-fork lifecycle ledger (RULE 0.12)

SQLite-backed append-only log of every non-trivial agent invocation. One row per fork; the orchestrator uses validate to check that the 6 required artefacts exist on the child branch before merging.

kei-ledger [--db <path>] <subcommand>
  init                                        — create ledger file + schema
  fork <id> <branch> --spec-sha <sha>         — log a new running agent
          [--parent <id>] [--worktree <path>]
  done <id> --summary <s>                     — mark running agent done
  fail <id> --reason <r>                      — mark running agent failed
  merged <id>                                 — mark done/failed agent merged into parent
  list [--status running|done|failed|merged]  — dump history
  tree <id>                                   — parent → children tree from root id
  validate <branch> [--repo-root <path>]      — check 6-artefact bundle exists
                                                (spec.md / plan.md / progress.json /
                                                 chatlog.md / handoffs.md / review.md)

State: $KEI_LEDGER_DB or ~/.claude/agents/ledger.sqlite. validate exits 2 if artefacts missing.

kei-migrate — universal SQL migration runner

Postgres / SQLite / MySQL via a single DATABASE_URL. Up/down/status/create.

kei-migrate --database-url <url> [--dir <path=migrations>] <subcommand>
  up                  — apply all pending migrations
  down [n=1]          — revert the last N migrations (needs <ts>_<name>.down.sql)
  status              — list applied vs pending
  create <name>       — scaffold <ts>_<name>.sql (+ .down.sql)

URL formats accepted: postgres://..., sqlite:///abs/path.db or sqlite::memory:, mysql://.... Reads DATABASE_URL env var as fallback.

kei-changelog — Conventional Commits → Markdown

Git-cliff-shaped generator. Walks a commit range, groups by conventional-commit type, prepends to CHANGELOG.md or emits to stdout.

kei-changelog [--from <ref>] [--to <ref=HEAD>] [--unreleased]
              [--version <label=v0.1.0>] [--repo <path=.>]
              [--update <file>]

--update prepends under # CHANGELOG header (idempotent — won't duplicate an existing identical block). Without --update, prints to stdout.

ssh-check — sshd_config linter

Reads /etc/ssh/sshd_config + every sshd_config.d/*.conf, merges via last-wins, scores against the KeiSeiKit hardened-baseline rule matrix.

ssh-check [--config <path=/etc/ssh/sshd_config>]
          [--drop-in <dir=/etc/ssh/sshd_config.d>]
          [--allow-user <name>]... [--json]

Repeatable --allow-user for extra accepted AllowUsers entries (default: keiadmin). Exits 2 if violations found.

firewall-diff — ufw intent-vs-live diff

Defensive-only — does NOT execute ufw itself. Takes an intent YAML + a captured ufw status numbered output (file or stdin) and reports drift.

firewall-diff --intent <yaml> (--status-file <path> | --stdin) [--json]

Exit 2 on any diff. Use via ufw status numbered | firewall-diff --intent fw.yaml --stdin.

mock-render — WYSIWYD screenshot-and-lock

Playwright-backed. Enforces the "What You See Is What's Deployed" invariant: every site section's source file is hashed, the hash is locked against a screenshot, and verify fails if the source drifts after lock.

mock-render screenshot <url> --out <png> [--viewport WxH]
mock-render lock    --project <dir> --section <src> [--screenshot <png>]
mock-render verify  --project <dir> --section <src>
mock-render status  --project <dir>

Exit 2 on invariant violation (source hash changed since lock).

visual-diff — pixel PNG comparator

Used by site-wysiwyd-check hook to detect visual drift. Produces a red-overlay diff PNG when images differ beyond threshold.

visual-diff <a.png> <b.png> [--out <file=diff.png>] [--threshold <pct=1.0>]

Exit 2 if mismatch exceeds threshold. Prints percentage + diff-px count.

tokens-sync — design tokens → Tailwind + CSS vars

Single JSON file → Tailwind theme.extend config and CSS :root custom properties. Either or both output targets; at least one required.

tokens-sync <tokens.json> [--out-tailwind <path>] [--out-css <path>]

JSON minimum shape: { colors, fonts, spacing, radius }.

kei-memory — session retrospective + pattern detector (RULE 0.14)

Offline TF-IDF / recurrence analyzer powering /self-audit. Ingests JSONL transcripts, surfaces cross-session patterns.

kei-memory [--db <path>] <subcommand>
  ingest --session-id <id> --transcript <path.jsonl> [--prompt <text>]
  analyze [--session <id>] [--last <n=1>] [--summary]
  patterns [--cross-session] [--session <id>]
  similar <prompt> [--limit <k=5>]          — top-k past sessions by TF-IDF cosine
  dump <session-id>                          — emit session events as markdown
  stats                                      — N sessions / N events / top tools
  backlog [--add <s>] [--list] [--clear]     — silent-first audit backlog

State: $KEI_MEMORY_DB or ~/.claude/memory/kei-memory.sqlite.

kei-conflict-scan — deep-sleep conflict scanner (v0.13.0)

Scans a memory-repo clone for rule conflicts, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations.

kei-conflict-scan --path <root>
                  [--format json|human] [--only rules|hooks|blocks|orphans|cp]
                  [--exit-on-hit]

Emits JSON (default) or human table. Exit 2 only when --exit-on-hit AND hits found.

kei-refactor-engine — refactor-plan generator (v0.13.0)

Consumes kei-conflict-scan JSON, emits plan markdown + an auto-resolve review file (NOT a unified diff — v0.14.1 retraction).

kei-refactor-engine [--input <conflicts.json>|-] [--plan-only]
                    [--apply-to-branch <branch>]
                    [--plan-out <path>] [--patch-out <path>]

--patch-out writes a markdown review (kept name for backward-compat). requires_human_decision items excluded from auto-resolve, listed in plain plan.

kei-graph-check — post-refactor graph-integrity gate (v0.13.0)

Resolves wikilinks + handoff refs + block refs across a memory-repo clone. Used as a gate BEFORE orchestrator commits the deep-sleep fork branch.

kei-graph-check --path <root> [--after-diff <patch>] [--json]

--after-diff treats any +++ /dev/null removal or # removed: <p> header as a phantom-removed file. Exit 2 on any broken reference.

kei-store — memory-repo backend abstraction (v0.21)

Unifies GitHub / Forgejo / Gitea / Filesystem / S3 behind one MemoryStore trait. Real aws-sdk-s3 when built with --features s3; otherwise falls back to a local-manifest stub (still behind KEI_STORE_ALLOW_S3_STUB=1).

kei-store [--config <path>] <subcommand>
  init <backend> [--url <url>]      — write store-config.toml scaffold
  read <path>                        — fetch blob to stdout
  write <path> <file>                — upload local file
  list <dir>                         — list names under dir
  branch <name>                      — set active branch/prefix
  commit --message <msg>             — commit staged writes
  push <branch>                      — push branch to remote
  pull <branch>                      — pull branch from remote
  status                             — print backend name

Config: ~/.claude/agents/_primitives/store-config.toml (override with --config). S3 endpoint override: KEI_STORE_S3_ENDPOINT env or s3.endpoint TOML field. AWS default credential chain applies.

kei-artifact — typed artifact handoff store (v0.16)

JSON-Schema-validated blob store for inter-agent handoffs. Five built-in schemas: spec, plan, patch, review, research. Custom schemas registered at runtime auto-sync to the assembler via schemas.json export.

kei-artifact [--db <path>] <subcommand>
  init                                              — register 5 built-in schemas
  register-schema --name <n> --path <schema.json>
  list-schemas
  export-schemas [--path <out>]                     — refresh assembler's schemas.json
  emit --schema <n> --from <agent> --content <json> — write an artifact
       [--meta key=val]... [--parent <id>]
  get <id> [--format typed|raw]
  list [--schema <n>] [--from <agent>] [--since <N>s]
  validate <id>                                      — re-validate against schema
  chain <id>                                         — walk parent-handoff chain

State: $KEI_ARTIFACT_DB or ~/.claude/artifacts/artifacts.sqlite.

kei-auth — HMAC-signed token issuer (v0.14.1 security fix)

Issue / verify / revoke. Signing secret sourced from KEI_AUTH_KEY env var ONLY — the old --key CLI flag was removed in v0.14.1 because it leaked the secret through /proc/<pid>/cmdline and shell history.

kei-auth [--db <path>] <subcommand>
  issue  --user <u> --project <p> [--scope read|write|admin=read] [--ttl <sec=86400>]
  verify <token>
  revoke <token>

Key source (per RULE 0.8): export KEI_AUTH_KEY="$(openssl rand -hex 32)" or sourced from ~/.claude/secrets/.env. State: $KEI_AUTH_DB or ~/.claude/auth/auth.sqlite.

kei-router — natural-language → tool-call JSON

Rule-based NL router. Parses a short query into a structured tool-call JSON object. Used by the compose-solution skill as a first-pass dispatcher.

kei-router <query> [--forward]

--forward adds _forward=true hinting remote-MCP forwarding on fallback. Prints pretty JSON to stdout.

kei-sage — Obsidian-style knowledge vault

SQLite-backed FTS5 knowledge store with BFS-related and PageRank. Can import an Obsidian vault wholesale.

kei-sage [--db <path>] <subcommand>
  import <vault>                                    — import .md files with frontmatter
  search <query> [--limit <n=20>]                   — FTS5 over title+content
  related <key> [--depth <d=2>]                     — BFS from a vault path/key
  rank [--limit <n=20>]                             — PageRank over wikilinks
  add --title <t> [--content <c>] [--vault-path <p>] [--grade <g=E4>]
  edit <id> [--title <t>] [--content <c>] [--grade <g>]
  link <src> <dst> [--edge-type <t=related>]

State: $KEI_VAULT_DB or ~/.claude/sage/vault.sqlite.

kei-task — task DAG CLI

SQLite task graph with dependencies, milestones, FTS search. Dep types arbitrary (blocks, relates, ...).

kei-task [--db <path>] <subcommand>
  create <title> [--description <d>] [--priority low|medium|high=medium]
  update <id> [--status <s>] [--title <t>]
  add-dependency <from> <to> [--dep-type <t=blocks>]
  graph                                — list all edges
  dependency-chain <id>                — topologically walk deps
  search <query> [--limit <n=20>]
  milestone <name> [--description <d>]
  link-milestone <task-id> <milestone-id>

State: $KEI_TASK_DB or ~/.claude/task/task.sqlite.

kei-chat-store — chat session archive

Session + message CRUD with token/cost accounting, FTS search, archive flag.

kei-chat-store [--db <path>] <subcommand>
  start --project <p> [--title <t>] [--model <m>]
  save --session-id <id> --role <user|assistant|system> <content>
       [--tokens-in <n>] [--tokens-out <n>] [--cost <f>]
  search <query> [--limit <n=20>]
  archive <session-id>
  stats                                — JSON summary

State: $KEI_CHAT_DB or ~/.claude/chat/chat.sqlite.

kei-crossdomain — cross-domain link graph

Generic typed-edge graph for linking any URIs. Used to wire rules ↔ memory ↔ artefacts ↔ chats.

kei-crossdomain [--db <path>] <subcommand>
  link <from> <to> [--edge-type <t=related>] [--weight <w=1.0>] [--evidence <g=E4>]
  unlink <from> <to> [--edge-type <t=related>]
  query <node>                         — all edges touching node
  graph <start> [--depth <d=2>]        — BFS
  auto-link <node>                     — propose + add edges via heuristic
  stats                                 — count per edge type

State: $KEI_CROSS_DB or ~/.claude/cross/cross.sqlite.

kei-search-core — research pipeline scaffold

Budget-bounded research runner. Current build ships a StubFetcher (real web fetch pluggable); runs the research-pipeline cubes end-to-end and persists results for markdown/JSON export.

kei-search-core [--db <path>] <subcommand>
  run <prompt> [--budget <microusd=1_000_000>]   — default budget = 1 USD
  stop <id>
  export <id> [--format md|json=md]

State: $KEI_SEARCH_DB or ~/.claude/search/research.sqlite.

kei-content-store — creative asset + prompt registry

Register generated assets, prompts, campaigns; track prompt version history.

kei-content-store [--db <path>] <subcommand>
  register-asset <title> [--file-path <p>] [--media-type <m>] [--provider <n>]
  register-prompt <prompt-text> [--model <m>] [--prompt-type <t>]
  create-campaign <name> [--description <d>]
  attach-asset <campaign-id> <asset-id>
  prompt-history <prompt-id>

State: $KEI_CONTENT_DB or ~/.claude/content/content.sqlite.

kei-social-store — people + organisation CRM

Person/org registry with interaction log + relationship graph.

kei-social-store [--db <path>] <subcommand>
  search-people <query> [--limit <n=20>]
  add-person <name> [--email <e>] [--handle <h>] [--source <s=manual>]
  add-org <name> [--org-type <t=company>]
  log-interaction <person-id> <interaction-type> [--content <c>]
                  [--channel <ch=manual>] [--target-id <n>]
  relationship-graph

State: $KEI_SOCIAL_DB or ~/.claude/social/social.sqlite.

kei-curator — edge decay + orphan pruning

Operates on any of the kei-sage / kei-crossdomain SQLite databases. Periodic cleanup: exponential decay on edge weights, prune orphans.

kei-curator --db <path> <subcommand>
  decay [--default-lambda <λ=0.05>] [--threshold <θ=0.1>]
  prune-orphans

Requires an explicit --db <path> — there is no default.

keisei — exobrain multi-client CLI (v0.19+)

Entry-point that mounts a portable brain directory into one or more AI clients. See the dedicated deep-dive section below.

Shell primitives

All 13 live under _primitives/*.sh. Installed with chmod +x at ~/.claude/agents/_primitives/. Shell primitives are POSIX sh where feasible; two (provision-hetzner, provision-vultr, harden-base) use bash explicitly.

tomd.sh — universal format → markdown

Converts PDF / DOCX / DOC / HTML / PPTX / XLSX / CSV / images / source code to markdown. Used by the tomd-preread hook to auto-convert binary formats before Claude reads them. Deps: pandoc, python3, jq. Optional: pymupdf4llm (better PDF), openpyxl (XLSX tables), tesseract (OCR).

design-scrape.sh — Playwright site scrape

Scrapes a live URL into tokens + section map + desktop/mobile screenshots.

design-scrape <url> [--out <dir>]

Output: <out>/desktop.png, <out>/mobile.png, <out>/tokens.json, <out>/structure.json. Requires npx + Playwright chromium.

live-preview.sh — dev-server wrapper

Detects framework from package.json, runs npm run dev, writes PID to .keisei/dev-server.pid for the site-wysiwyd-check hook to discover.

live-preview start <dir>
live-preview stop  [pid]       — default: reads .keisei/dev-server.pid
live-preview status

figma-tokens.sh — Figma → tokens.json

Fetches Figma Variables + Styles via REST API, emits a tokens.json consumable by tokens-sync.

FIGMA_TOKEN=figd_xxx figma-tokens <file-key> [--out <path=tokens.json>]

Token MUST come from env (RULE 0.8). File-key is the segment after /design/ or /file/ in the Figma URL.

frontend-inspect.sh — project fingerprint

Reports framework (Astro / Next / SvelteKit / Vite-React / static / unknown), styling (tailwind4 / tailwind3 / css-modules / plain), package manager, component count, whether tests exist.

frontend-inspect [<dir>] [--json]

screenshot-decode.sh — vision-API screenshot → structured description

Posts a PNG + prompt to the Anthropic Messages API (claude-sonnet-4) and prints the text response.

ANTHROPIC_API_KEY=sk-ant-xxx screenshot-decode <png> [--prompt <text>]

Default prompt asks for token + layout + sections as JSON. API key MUST come from env (RULE 0.8).

metrics-scrape.sh — Prometheus /metrics scraper

Scrape + format / filter / alert-check. POSIX sh.

metrics-scrape <url>                                  # table (default)
metrics-scrape <url> --format json                    # needs jq
metrics-scrape <url> --format alert-check --filter <re> --threshold <n>
metrics-scrape <url> --filter '^http_requests_total'

alert-check format exits non-zero if any filtered metric exceeds threshold.

log-ship.sh — structured log tee + forward

Pipes JSON-line logs from stdin to stdout and optionally forwards to Loki / Datadog / generic HTTP. Local tee ALWAYS happens, even if forward fails — observability must degrade gracefully.

cat log.jsonl | log-ship --target stdout
journalctl -o json | log-ship --target loki --endpoint http://loki:3100/loki/api/v1/push --label job=api
tail -f app.log | log-ship --target datadog --endpoint <dd-url>
cat log.jsonl | log-ship --target http --endpoint <url>
cat log.jsonl | log-ship --target stdout --validate

Env (no CLI token leak): LOG_SHIP_DD_API_KEY, LOG_SHIP_BEARER.

provision-hetzner.sh — Hetzner Cloud provisioner

Idempotent wrapper over hcloud CLI. Re-running create <name> on an existing server prints its IP and exits 0.

provision-hetzner create <name> [--type cx22|cax11] [--location fsn1]
                                [--image debian-12] [--ssh-key <id>]
                                [--firewall <name>] [--user-data <file>]
provision-hetzner status  <name>
provision-hetzner destroy <name> [--force]
provision-hetzner list

Env (RULE 0.8): HCLOUD_TOKEN.

provision-vultr.sh — Vultr provisioner

Same shape as Hetzner. Uses vultr-cli v3.

provision-vultr create <label> [--plan vc2-1c-1gb] [--region ams]
                               [--os-id 2136] [--ssh-key <id>]
                               [--firewall <group-id>] [--user-data <file>]
provision-vultr status  <label>
provision-vultr destroy <label> [--force]
provision-vultr list

Env (RULE 0.8): VULTR_API_KEY. Idempotency key is the human label field.

harden-base.sh — post-provision baseline hardening

Runs ON the target VPS. Ports generic patterns from Vortex setup.sh (apt, ssh drop-in, ufw, fail2ban, auditd, unattended-upgrades). Never reboots — surfaces needrestart hints only.

sudo bash harden-base.sh [--admin-user <name=keiadmin>] [--ssh-port <n=22>]
                          [--allow-port <n/proto>]... [--no-caddy]
                          [--no-reboot] [--skip apt|ssh|ufw|fail2ban|auditd|unattended]

Every step is test → configure → reload — re-running is safe.

kei-ci-lint.sh — GitHub/Forgejo Actions linter

7 rule suite (R1-R7): required fields, least-privilege permissions, OIDC-vs-long-lived-token, cache-hit hygiene, SHA pinning, deprecated-action flags, pwn-request pattern.

kei-ci-lint <file.yml> [file2.yml ...]
kei-ci-lint --dir .github/workflows [--warn]
kei-ci-lint --dir .forgejo/workflows

Requires yq v4+ (mikefarah/yq Go impl — not the Python one).

kei-docs-scaffold.sh — auto-doc generator

Detects project type (Cargo.toml / package.json / pyproject.toml / pubspec.yaml / go.mod / Package.swift / docker-compose), emits CLAUDE.md / DECISIONS.md / runbook / README.

kei-docs-scaffold [--type=all|claude|decisions|runbook|readme]
                  [--force] [--dry-run] [DIR]

Default: --type=all. Idempotent without --force.

Hooks

All 10 kit-shipped hooks live under hooks/*.sh, get copied to ~/.claude/hooks/ on install. Every hook respects KEI_DISABLED_HOOKS and KEI_HOOK_PROFILE (see Runtime hook controls below). Silent fall-through on missing jq — never aborts a tool call system-wide.

Hook	Event	Severity	Bypass
assemble-agents	PostToolUse:Edit|Write	advisory (rebuilds; never blocks)	—
assemble-validate	PreToolUse:Bash	block — exit 1 on git commit in ~/.claude when manifests fail validation	—
no-hand-edit-agents	PreToolUse:Edit|Write	block — exit 2 on generated .md edit attempts	AGENT_MIGRATION=1
tomd-preread	PreToolUse:Read	redirect — exit 2 with stderr pointing to cached .md	—
agent-fork-logger	PreToolUse:Agent	advisory (logs to kei-ledger; silent if absent)	—
orchestrator-dirty-check	PreToolUse:Agent	warn (stderr only)	ORCHESTRATOR_META=1 or ORCHESTRATOR_DIRTY_OK=1
site-wysiwyd-check	PostToolUse:Edit|Write	warn (stderr drift report)	—
session-end-dump	Stop	advisory (archives trace + calls kei-memory ingest)	—
milestone-commit-hook	PostToolUse:Bash	advisory (appends to audit-backlog on feat:/refactor:/merge)	—
error-spike-detector	PostToolUse:*	warn (stderr when ≥3 errors in 20-call window)	—

Details beyond the table:

• assemble-agents — diff source: _manifests/*.toml rebuilds one agent; _blocks/*.md rebuilds ALL. Calls _assembler/target/release/assemble --in-place.
• assemble-validate — only fires when git commit runs inside ~/.claude; validates every manifest; stderr-lists failures and exits 1 on any.
• no-hand-edit-agents — SSoT marker is <!-- GENERATED by _assembler --> on line 1. Files without the marker pass silently (legacy hand-authored agents). AGENT_MIGRATION=1 overrides during migration only.
• tomd-preread — whitelist: .docx, .doc, .xlsx, .pptx, .csv. Cache key: basename + mtime + short path-hash (prevents collision between two same-basename files). Cache dir: $KEISEI_TOMD_CACHE or /tmp/keisei-tomd-cache.
• agent-fork-logger — extracts subagent_type + prompt + isolation; branch = agent/<slug>-<ts> when isolation=worktree, else inline-<slug>-<ts>. Spec-SHA = first 16 hex chars of SHA-256(prompt).
• orchestrator-dirty-check — runs git status --porcelain on repo root, stderr-warns with modified + untracked counts.
• site-wysiwyd-check — triggers on .tsx / .vue / .svelte / .astro / .css / .html / .jsx / .ts. Walks up to find .keisei/dev-server.pid; bails if no live server or no .keisei/target.png.
• session-end-dump — copies transcript JSONL to ~/.claude/memory/traces/<session_id>.jsonl, calls kei-memory ingest, then best-effort calls kei-sleep-sync.sh (RULE 0.15, silent if sleep-sync not opted in).
• milestone-commit-hook — case-sensitive prefix match on feat:, refactor:, merge (avoids false-firing on feature-docs.md).
• error-spike-detector — rolling window in ~/.claude/memory/error-window.txt; error-classifier = is_error=true OR message matches /error:|failed|panic|denied/i.

Skills (grouped)

39 skills under skills/<name>/SKILL.md. Each is invoked as /<skill-name> inside Claude Code. Free-text is used only for intake fields; every other decision is a click via AskUserQuestion.

Meta / project setup (4)

Skill	One-liner
/compose-solution	Meta-orchestrator — converts a free-text task into the right artefact (agent / skill / hook / rule / block) by composing existing primitives. Enriches _blocks/ over time.
/new-project	4-phase bootstrap — intake, fork skeleton (branch + ledger row + sub-agent spawn), parallel execution with progress aggregation, per-branch merge ceremony. RULE 0.12 at project scale.
/new-agent	Interactive 6-question wizard that builds a project-specialist manifest and its .md.
/onboard	Scan a project (or scope) and propose agents + hooks + primitives based on detected stack. Three modes: Full auto, Step-by-step, Full manual.

Design / frontend (18)

Skill	One-liner
/site-create	End-to-end site pipeline — intake → design → sections → WYSIWYD mock-render loop → audits → preview → deploy. The verify gate HARD-BLOCKS deploy of unlocked sections.
/site-builder	Build a site from block recipes. WYSIWYD invariant via mock-render.
/site-teardown	Deconstruct any live site into a reusable recipe — HTML, CSS, JS, tokens, animations.
/landing-page	Orchestrates design + copy + assets + animations + SEO for a landing page. Supports recipes (apple-product, saas, portfolio, ecommerce).
/design-system	Build a design system — tokens, base components, Tailwind config, dark mode, docs.
/ui-component	Build a UI component — API design, variants, a11y, animations, tests.
/form-builder	Multi-step forms — Zod validation, Turnstile anti-spam, serverless backends, upload, progressive enhancement.
/scroll-animation	Scroll-driven animation — GSAP ScrollTrigger, CSS scroll-timeline, parallax, pin/scrub.
/motion-design	Motion design — page transitions, element animations, View Transitions API, Rive/Lottie, a11y.
/web-effects	Visual web effects — WebGL shaders, particles, noise/grain, displacement maps, CSS-only.
/web-assets	Image / font / video optimization — AVIF, responsive srcset, font subsetting, Sharp.js.
/figma-to-code	Figma design → code — screenshot, context, tokens, responsive implementation.
/frontend-design	Anti-AI-slop aesthetic philosophy — typography pairing, color theory, spatial composition, motion guidelines, design archetypes.
/responsive-audit	6-breakpoint audit — layout, touch targets, overflow, images.
/a11y-audit	WCAG 2.2 AA compliance — contrast, keyboard nav, screen reader, prefers-reduced-motion.
/perf-audit	Perf baseline → profile → top-3 bottlenecks → fix → remeasure.
/seo-audit	Technical + content SEO via WebFetch + code inspection.
/web-deploy	Cloudflare Pages / Vercel / edge functions / caching / Core Web Vitals / CI/CD / DNS.

Infra / ops (4)

Skill	One-liner
/vm-provision	End-to-end VPS — provider → plan → provision → harden → ssh-check + firewall-diff hard-gate → handoff. Stops if either verification fails.
/ci-scaffold	Production CI/CD plan — platform (GitHub vs Forgejo), build matrix, OIDC-vs-token, release automation, security gate. Emits workflow YAML + runs kei-ci-lint.
/observability-setup	Logs + metrics + traces triad on an existing service — instrumentation → scrape+ship → dashboard → alerts.
/auth-setup	Production auth/IAM plan — user flows, IdPs, session strategy, authorization model, threat mitigations. Never writes secret values.

API / schema / docs / tests (5)

Skill	One-liner
/api-design	API design — style (REST / GraphQL / tRPC / gRPC), resource model, OpenAPI 3.1 or GraphQL SDL, versioning, rate-limit + auth handoff, codegen.
/schema-design	Relational schema → migrations → kei-migrate apply. PG / SQLite / MySQL autodetect.
/docs-scaffold	5-phase — detect project type, audit existing docs, generate CLAUDE.md / DECISIONS.md / runbook / README / diagrams / CHANGELOG.
/test-matrix	Beyond-unit test stack — fuzzing, property-based, load, E2E, mutation. Composes right mix per language × critical path × CI target.
/test-gen	Generate tests for untested code — happy path, edge cases, error handling.

Retro / audit / research (5)

Skill	One-liner
/self-audit	RULE 0.14 session retrospective triage — runs kei-memory analyze + patterns, routes findings to /escalate-recurrence / /debug-deep / audit-backlog.
/pr-review	PR review — Constructor Pattern awareness, security, SSoT check.
/refactor	Refactor with behavior preservation — checkpoint, extract, test, audit.
/debug-deep	5-phase RCA using multi-agent analysis + error pattern matching.
/research	Deep research via parallel agents + web search + cross-referencing.

Sleep layer + runtime (3)

Skill	One-liner
/sleep-setup	RULE 0.15 one-time wizard — local-only / remote-only / hybrid, trigger time, memory-repo init, SSH deploy key, /schedule create + cron snippet.
/sleep-on-it	v0.12 incubation — defer a question to the nightly remote agent. Up to 5 tasks per night (15 min each). Priority maps to budget.
/hooks-control	v0.15.1 click-only runtime enable/disable — emits shell export / unset for user to paste. Does NOT execute anything itself.

keisei CLI — exobrain entry point

keisei is the only Rust primitive that mounts state into OTHER tools' configs. It reads a portable brain directory (see brain layout above) and writes mcpServers.keisei entries into each detected AI client's config file.

Five subcommands (every flag listed is the actual clap arg surface in _primitives/_rust/keisei/src/main.rs):

keisei attach <brain-path> [--scope user|project]
keisei mount  <brain-path>
keisei detach
keisei status
keisei list-adapters

Flag matrix:

Subcommand	Required args	Flags	Notes
attach	<brain-path> (dir with manifest.toml)	--scope user|project (default user)	Attaches to the first detected client. Adapters that don't support requested scope error out cleanly.
mount	<brain-path>	—	Auto-attach to EVERY detected AI client. Always user-scope (host-wide fan-out by design).
detach	—	—	Removes mcpServers.keisei from every client in the marker; preserves the user's other MCP entries. Deletes marker.
status	—	—	Brain name + path + attach timestamp + per-client config path + health (brain root is a dir? mcp_server binary exists?).
list-adapters	—	—	Tabular view: name / detected / config_path / scopes.

Supported adapters (v0.21): Claude Code, Cursor, Continue, Zed. Claude Code and Cursor advertise both user + project scope. Continue and Zed are user-only.

Exit codes:

• 0 — success
• 1 — error (brain validation fail, no adapter detected, NameConflict, scope unsupported, IO)

No separate exit code for "config invalid" — all errors funnel through exit 1 with the specific message printed to stderr. (The task brief mentioned exit 2 for config-invalid, but the current main.rs only returns ExitCode::SUCCESS or ExitCode::from(1).)

Env vars:

Var	Purpose
KEISEI_HOME	Test hook — overrides $HOME for marker-file resolution and adapter config-path lookup
KEI_STORE_S3_ENDPOINT	Custom S3-compatible endpoint (R2 / MinIO / Wasabi) — consumed by kei-store when built with --features s3
KEI_STORE_ALLOW_S3_STUB	Set to 1 to permit the local-manifest S3 stub when the real s3 feature isn't built
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION	Standard AWS credential chain — consumed via aws-sdk-s3 default resolver
KEI_AUTH_KEY	HMAC secret for kei-auth (NOT a CLI flag since v0.14.1)

Marker SSoT: ~/.keisei/attached.toml (v0.21+). Schema v3 entries have a scope field. Legacy ~/.claude/keisei-attached.toml auto-migrates on first read (one-shot: legacy deleted, new location written, stderr notice printed).

Security hardening (v0.19):

• Brain mcp_server path MUST be relative + inside the brain root (rejects /usr/bin/curl, ../../etc/shadow, Windows-style ..\..\)
• Brain name matches ^[a-z][a-z0-9_-]{0,63}$
• Brain root rejected if it's a symlink (blocks USB → $HOME pivot)
• Adapters refuse to clobber existing mcpServers.<name> entries — explicit NameConflict error, no silent overwrite
• All config writes go through fsx::write_atomic_json (Windows-safe via tempfile::NamedTempFile::persist)

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.