KeiSeiKit-1.0/README.md

KeiSeiKit

A multi-LLM substrate for agentic coding. Same agent definition, any LLM backend — Claude Code, Grok, Antigravity (Gemini), GitHub Copilot, or Kimi. Pick your orchestrator with kei pick; agents spawn sub-agents on other LLMs via MCP spawn_agent; safety hooks enforce on every backend through a 3-tier model. Three-phase nightly sleep consolidates 30-session windows into morning markdown reports.

Apache 2.0 — explicit patent grant + retaliation clause.

Highlights

• 5 LLM CLIs unified. Claude Code (native hooks), Grok (port to ~/.grok/settings.json), Antigravity/Gemini, GitHub Copilot, Kimi. DNA-routed: each agent's manifest declares a provider; kei agent <name> resolves DNA → primary → claude fallback.
• Sub-agents on any backend. Agents call spawn_agent (built-in MCP tool in kei-mcp) to dispatch other agents to whichever LLM fits the task. Cross-CLI orchestration without lock-in — Grok can spawn critic@Claude, then ml-implementer@Gemini, all from one session.
• 3-tier policy enforcement. Claude + Grok TIER 1 (full native PreToolUse), Copilot TIER 2 (MCP-wrapped + --excluded-tools=shell), Agy + Kimi TIER 3 (advisory). no-github-push, safety-guard, destructive-guard, citation-verify, numeric-claims-guard surface on every backend that supports tool-call gating.
• Three-phase nightly sleep. Phase A (incubation — queued tasks via /sleep-on-it), Phase B (REM consolidation — analyzes last 30 sessions, writes morning markdown), Phase C (NREM deep-sleep, every 7 days — conflict scan + refactor proposals). Outputs are markdown; you decide what merges.
• Native token streaming. Each backend streams in its own print mode (claude -p, grok --print, agy --print, copilot --prompt); KeiSeiKit composes the agent prompt + task and passes through. No buffering layer.
• Persistent memory. SQLite ledger + content-addressable store, session-spanning context, cross-machine sync via memory-repo.
• Agent DNA. Deterministic variable-length identity per invocation: <role>::<caps>::<scope-sha8>::<body-sha8>-<nonce8>. Same task → same prefix → "did this run before?" via SQL, no embeddings.
• Constructor Pattern. Substrate, not framework. You compose; it doesn't dictate workflow. File >200 LOC → decompose. No mixins, no DI containers, no abstract factories.
• Self-maintaining. Every substrate edit cascades: registry updates, agent regeneration, DNA index refresh, keimd graph reindex. Auto-self-indexing via kei-registry SQLite.

By the numbers (v0.47)

110 Rust crates · 69 skills · 54 hooks · 38 agent manifests · 86 substrate blocks · 18 capability atoms · 7 substrate roles · 565 indexed DNAs · 6 install profiles (minimal → full).

Platforms

• macOS (arm64 + x64) — fully supported, primary dev target.
• Linux (Ubuntu, Debian, Fedora, Arch — x64 + arm64) — fully supported.
• Windows — substrate itself is Bash-only, but the MCP server binary ships as kei-mcp-server-windows-x64.exe in every release. Two recommended paths:
  • WSL2 (recommended) — install Windows Subsystem for Linux, then run bootstrap.sh inside Ubuntu/Debian as normal. Full substrate works.
  • MCP-only — drop kei-mcp-server-windows-x64.exe into your Claude Desktop / VS Code MCP config to get spawn_agent + kei_bash/kei_edit/kei_write tools, without the full Bash-based substrate. Skills, hooks, and kei CLI not available in this mode.
  • Native PowerShell port: not on the roadmap (would double maintenance surface; WSL gives 100% coverage with 0 duplication).

Maturity matrix

The substrate ships as a layered set of components at different maturity levels. Read this before relying on any single piece for production work.

Component	Status	Notes
24+ Rust primitives	varies (alpha → beta → concept)	Inspect each crate's Cargo.toml package.metadata.keisei.maturity if declared; otherwise treat as alpha unless you've personally exercised it. Most primitives are alpha — they build, type-check, and have unit tests, but have not been hardened against adversarial input or run at scale.
Cortex daemon (kei-cortex HTTP + WS)	alpha	CLI-driven daemon works in author's daily use; HTTP REST + WS endpoints + 8-tool /chat agentic loop build clean. Browser app (cortex-ui) and VSCode extension (@keisei/vscode-cortex) are concept-level — scaffolds present, not production paths.
MCP server (@keisei/mcp-server)	alpha	Published to keigit.com (https://keigit.com/api/packages/keisei/npm/) — author-operated Forgejo npm registry on a public DNS. Configure your ~/.npmrc per docs/PUBLISHING.md, then npm install @keisei/mcp-server. Local dist build still works for development (see Quick start).
Sleep layer (Phase A / B / C)	alpha	Phase A queue (/sleep-on-it → cloud agent) + Phase B markdown morning report work. Auto-codification of rules from sleep insights is not yet wired — codification path is manual via /escalate-recurrence. Phase C deep-sleep refactor proposals run on a 7-day cadence and write plan-only markdown by default.
Hooks (35 shipped)	beta	Tested in author's daily use (4–8 parallel Claude Code terminals). Pipeline hooks (assemble-agents, no-hand-edit-agents) are load-bearing; advisory hooks (RULE 0.12 / 0.13 / 0.14) are non-blocking.
Skills + manifests + assembler	beta	Structured + assembler-validate gate runs on every git commit inside ~/.claude. Schema is locked (see docs/AGENT-SCHEMA-LOCKED.md).

What it does

Persistent memory	SQLite ledger + content-addressable memory store, session-spanning context, cross-machine sync via memory-repo
Agent DNA	Deterministic variable-length identity per invocation: <role>::<caps>::<scope-sha8>::<body-sha8>-<nonce8> (≥33 chars; role + caps slugs are variable). Same task → same prefix → "did this run before?" via SQL, no embeddings. See docs/DNA-FORMAT.md for the wire spec.
Constructor Pattern for prompts	Agent .md files composed from manifests + blocks + capability bundles + rule fragments. Edit a block → all agents using it recompose. Single source of truth
kei-fork	Atomic git triplet (branch + worktree + ledger row) for parallel agent runs. Atomic rollback. No main-branch collisions across 4-8 simultaneous Claude sessions
Three-phase sleep	Phase A incubation (queued tasks) → Phase B REM consolidation (analyzes last 30 sessions, writes morning markdown report) → Phase C NREM deep-sleep (every 7 days, conflict scan + refactor proposals). No feedback loop — outputs are markdown, you decide what to keep
Auto self-indexing	Every substrate file edit triggers registry update + agent regeneration + DNA-INDEX.md refresh + keimd graph reindex
Foreign-project ingestion	kei-import <repo> walks → matches against 12 runtime traits → extracts skills from README/docs → generates migration plan → produces per-phase agent prompts
Cross-tool bridges	One rule-set, 11 target formats (.cursorrules, .windsurf/rules/main.md, .github/copilot-instructions.md, AGENTS.md, GEMINI.md, etc)
npm-style publishing path	Publish your agents / skills / hooks as scoped packages. The author runs an opt-in mirror at keigit.com (public Forgejo + npm registry, OAuth, per-user PAT) — this is an author-operated mirror (KeiSei84 / private Forgejo), not a neutral community service. The substrate is remote-agnostic; use any git remote and any npm registry you trust. See docs/PUBLISHING.md

Why it exists

The author runs 4-8 parallel Claude Code terminals daily. Without substrate, every session loses context, every parallel agent collides on main, every "did we already solve this?" requires manual grep. With substrate, identity carries — agents know what ran before, results converge through the ledger, fork-as-triplet prevents collisions, three-phase sleep produces overnight consolidation.

This is a tool first, not a product. If it solves your problem, fork it.

Quick start

# Web installer (recommended — one line, no prior clone)
curl -fsSL https://install.keisei.app | bash
curl -fsSL https://install.keisei.app | bash -s -- --profile=dev --yes  # CI

# Claude Code (primary target — full hook + agent integration)
/plugin marketplace add KeiSeiLab/KeiSeiKit-1.0
/plugin install keisei@keisei-marketplace

# Any MCP-compatible client (Cursor / Continue / Zed / Aider / etc)
git clone https://github.com/KeiSeiLab/KeiSeiKit-1.0.git
cd KeiSeiKit-1.0
./bootstrap.sh                    # interactive profile picker
# or: ./install.sh --profile=minimal   # direct

The web installer (web-install.sh in this repo, served at install.keisei.app) is a thin curl-pipeable wrapper that clones the repo and delegates to bootstrap.sh — single source of truth, no duplicated install logic.

38 agents + 69 skills + 54 hooks + nightly consolidation wired in ~60 seconds. Twelve install profiles (outcome-only, minimal, core, frontend, ops, dev, mcp, cortex, local-mirror, dashboard, full-hub, full) defined in _primitives/MANIFEST.toml and documented in docs/INSTALL.md. For non-Claude-Code clients (Cursor / Continue / Zed / Aider) the bridges format the same source into client-native config — those are bridge targets, not separate profiles.

Post-install — the kei CLI (v0.45+)

After install, kei is the substrate entrypoint. On first interactive run an onboarding wizard walks you through picking a primary LLM orchestrator and wiring kei-mcp into the CLIs you have installed:

kei                              # launch primary CLI (default: claude)
kei onboard                      # post-install wizard (re-runnable)
kei pick                         # interactive primary picker
kei primary [<backend>]          # get/set primary LLM provider

kei agent <name> "<task>"        # invoke agent: backend from DNA → primary
kei agent --on=grok <name> "..." # invoke agent on a specific backend
kei run-via <backend> <name> "<task>"   # explicit-backend dispatch

kei mcp-wire                     # wire kei-mcp into all installed CLIs
kei mcp-wire --list              # show enforcement tier per CLI

kei limits                       # honest subscription-quota report
                                 # (4 of 5 CLIs have no public API)

kei configure                    # re-pick hook packs + stack profile
kei message ...                  # cross-session mailbox
kei --status                     # splash with substrate health

Multi-LLM agent dispatch

Agents are markdown prompts that can be served by ANY of 5 supported CLIs (Claude Code, Grok, Antigravity-Gemini, GitHub Copilot, Kimi). Each agent's manifest may declare a provider field that becomes its DNA; kei agent <name> then routes to that provider automatically. See docs/encyclopedia/multi-cli-agents.md.

Cross-CLI policy enforcement

KeiSeiKit's safety hooks (no-github-push, safety-guard, destructive-guard, citation-verify, numeric-claims-guard) extend to non-Claude CLIs through a 3-tier enforcement model:

• TIER 1 — full native: Claude (existing) + Grok (ports our hooks to ~/.grok/settings.json)
• TIER 2 — MCP-wrapped: Copilot (--excluded-tools=shell + force kei_bash via MCP)
• TIER 3 — advisory: Agy + Kimi (cannot disable native shell; prompt-level only)

See docs/encyclopedia/cross-cli-policy.md for the full matrix + setup.

Outcome-only — try just the outcome loop (5 files, ~200 LOC)

If you want to try only the outcome-tracking primitive without committing to the full kit (no daemon, no Forgejo, no launchd, no 100 crates), run ./install.sh --profile=outcome-only. Installs 2 hooks + a SQLite ledger + one line in ~/.claude/CLAUDE.md; uninstalls in four lines. See docs/PROFILE-OUTCOME-ONLY.md.

Self-maintaining

After install, the substrate maintains itself. Every edit cascades:

edit any rule .md       → kei-decompose registers fragments
edit any manifest .toml → assembler regenerates one agent .md
edit any block .md      → assembler regenerates ALL agents
edit any skill SKILL.md → kei-registry updates
edit any hook .sh       → kei-registry updates
edit any primitive src/ → kei-import-project register updates
ANY substrate edit      → DNA-INDEX.md auto-refreshes
ANY substrate edit      → keimd graph auto-reindexes

nightly:
  Phase A (incubation)         → process queued tasks
  Phase B (REM consolidation)  → analyze last 30 sessions → morning report
  Phase C (NREM, every 7d)     → conflict scan + refactor proposals

No automatic feedback loop into agent state. All consolidation outputs are human-readable markdown. You read, you decide what merges.

Honest limits

• Phase 5 executor (kei-import-project) generates per-phase agent prompts as JSON; the actual Agent({...}) spawn happens orchestrator-side (Claude Code Agent tool, MCP wrapper, or a thin shell loop). A first-class JS/TS wrapper that auto-spawns + tracks is future work.
• Phase 9 Path A (model-router assembler-time rebake) — 37 agent manifests currently declare model: opus in frontmatter. The router uses a Beta posterior with Wilson-style lower confidence bound (δ=0.10, q*=0.70); it falls back to the manifest-declared default until the per-(task-class, model) lower-bound clears the quality bar — typically tens of successful observations per pair, not a discrete 100-row threshold (see _primitives/_rust/kei-model-router/src/select.rs:74-124). 3 outcome rows total today, posterior dominated by uniform prior Beta(1,1).
• Cortex stack (kei-cortex / kei-tty / kei-mcp) ships as alpha (CLI/daemon track) — downgraded from "beta" because two of the three intended frontends are not yet shipping. Local HTTP daemon + ratatui TUI + MCP stdio JSON-RPC build clean and run in the author's daily use. Browser app (cortex-ui) and VSCode extension (@keisei/vscode-cortex) are concept-level only — scaffolds exist, no production wiring. Treat the daemon + CLI as the supported surface; treat the GUI frontends as roadmap.
• @keisei/mcp-server npm package — published to keigit.com (the author-operated Forgejo npm registry, public DNS at keigit.com). To install from the registry:

  # ~/.npmrc — one-time setup
  echo "@keisei:registry=https://keigit.com/api/packages/keisei/npm/" >> ~/.npmrc
  echo "//keigit.com/:_authToken=<your-keigit-PAT>" >> ~/.npmrc
  # PAT scope: read:package (write:package only if you publish)
  
  npm install @keisei/mcp-server
  

  For local development without the registry round-trip:

  cd _ts_packages
  bun install && bun run -r build
  # output: _ts_packages/packages/mcp-server/dist/index.js
  

  Single-binary builds via bun build --compile are documented in _ts_packages/packages/mcp-server/BUILD.md (5-target matrix, ~85–95 MB per binary). package.json has publishConfig.registry pinned to keigit.com so an accidental npm publish from this repo cannot route to npm.org.
• Non-Claude clients integrate via MCP + bridges, not native hooks. PreToolUse / PostToolUse / UserPromptSubmit / Stop semantics are Claude Code primitives. Other clients get capability exposure but not the hook wire-up.

What it's NOT

• Not a Claude Code replacement — runs alongside, not instead-of
• Not a SaaS — local-first by default; hosted offering under consideration if community demand emerges (see Roadmap)
• Not enterprise — solo-maintained, no SLA, no dedicated support
• Not a framework — substrate. You compose; it doesn't dictate workflow

Roadmap

The substrate is functionally complete for solo-developer use. What might be valuable as a hosted service if there's demand:

• Cross-machine memory sync — DNA-indexed memory available across laptop + desktop + cloud Claude session
• Hosted Phase B/C nightly — traces consolidated by a remote agent, morning report delivered to inbox
• Encyclopedia search-as-API — query team substrate by DNA / role / capability across multiple agents

These are considered, not committed. Open an issue with your use-case if any of these would solve real pain. Until then: fork, run locally, file PRs.

Hermes — proof of foreign-architecture ingest

Ten phases of Nous Research's Hermes (MIT, Python agent framework) ingested into KeiSeiKit substrate through April 2026. Each Hermes concept lives as a KeiSeiKit primitive:

Hermes phase	KeiSeiKit landing
ShareGPT trajectory export	kei-export-trajectories crate
OpenAI-compat HTTP server	kei-llm-router providers + chat handler
Daytona sandbox backend	kei-backend-daytona (with toolbox proxy URL split)
Injection-guard on memory writes	wired through kei-memory::ingest + kei-pet::memory
Memory-nudge invoker	Invoker trait + MemoryStore Arc plumbed
SKILL.md skill format	kei-skills::SkillRegistry, consumed by kei-mcp
Skill-invocation aggregation	kei-ledger schema v8 + aggregate-skills CLI
Multi-platform gateway	kei-gateway (Telegram / Discord / Slack / CLI)
Cron / scheduler	kei-cron-scheduler parser+job+runner

The kei-import umbrella runs the same pipeline (decompose → match → extract-skills → plan → execute) on any Rust / TS / Python / Go repo. Hermes was the validation case; the runtime works on others.

Frontend design — anti-AI-slop philosophy

The frontend-design skill is a deliberate counter-position to the same-shape output of v0 / Lovable / Bolt:

• 10 archetypes — Editorial / Swiss / Brutalist / Minimal / Maximalist / Retro-Futuristic / Organic / Industrial / Art Deco / Lo-Fi. Each declares typography pairing + color palette + layout language + motion style.
• OKLCH color system — one --brand-hue controls the full palette, perceptually uniform.
• Phase Gate (mandatory before any code): purpose, archetype, the one differentiator, three anti-references, design tokens. Skip the gate = skip the skill.
• Hard bans: Inter / Roboto / Space Grotesk, purple gradients on white, centered card grids as default, hero → cards → testimonials template, linear easing on UI transitions.
• Diverge-Kill-Mutate loop when output feels generic.
• The Blur Test: at 20% visibility, layout silhouette must be distinguishable from anti-references.

Orchestrator skill landing-page composes 11 skills across 6 recipes (apple-product / saas / portfolio / ecommerce / agency / startup).

Architecture

Stack: Rust core (105 workspace crates, ≤2 MB each, 12-trait runtime

• plugin registry) + TypeScript glue (6 adapters: gmail / grok / recall / telegram / youtube / mcp-server). Backend impls cover:

Trait	Impls
ComputeProvider	bare-metal SSH, DigitalOcean, Linode, Vultr
GitProvider	Forgejo, Gitea, GitLab, Bitbucket
MemoryBackend	SQLite, Sled, Postgres, Redis
AuthProvider	Google OIDC, Apple Sign-In, WebAuthn passkeys, magic-link
NotifyChannel	Telegram, Discord, Slack, SMS (Twilio)
NetworkMode	WireGuard, OpenVPN, IPsec
LlmBackend	Anthropic, OpenAI, Kimi (Moonshot), MLX, llama.cpp, Ollama
ServiceManager	systemd

Declare which impl to use in ~/.keisei/config.toml; runtime resolves at startup. See docs/ARCHITECTURE.md, docs/PHILOSOPHY.md, docs/SUBSTRATE-SCHEMA.md, docs/IMPORT-RUNTIME.md, docs/PUBLISHING.md, docs/RULES-AS-BLOCKS.md, docs/DNA-INDEX.md.

License

Apache 2.0. Use, fork, ship, modify. Explicit patent grant + retaliation clause: contributors who sue any user over patents covered by their contributions lose their license to the work. Pre-2026-04-30 versions remain available under their original MIT terms (irrevocable). See LICENSE and NOTICE.