a4e667de10
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
196 lines
6.4 KiB
Markdown
196 lines
6.4 KiB
Markdown
# Quickstart — KeiSeiKit Cortex Stack in 5 Minutes
|
|
|
|
Local AI assistant with a browser UI, terminal client, and VSCode panel.
|
|
Backed by a Rust daemon on `127.0.0.1:9797`. No cloud. Bring your own
|
|
API keys.
|
|
|
|
This guide walks you from clean clone to a chat window in your browser.
|
|
For the full install matrix (MCP-only, USB brain, Docker, Nix, etc.) see
|
|
[INSTALL.md](./INSTALL.md).
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- macOS 13+ or Linux (Ubuntu 22.04+, Debian 12+, Alpine 3.19+).
|
|
- Rust toolchain (`rustup`, current stable). The installer builds 53
|
|
crates from source — first build is ~3-5 min on Apple Silicon, ~6-8
|
|
min on a modern x86 laptop.
|
|
- Python 3.9+ and `pip` (used as a subprocess for `faster-whisper`
|
|
STT — RULE 0.2 exception #6, no Python in the daemon core).
|
|
- `node >= 18` and `pnpm` (used to build the Svelte UI bundle).
|
|
- `ffmpeg` on `PATH` (whisper audio demux).
|
|
- `git` and `sqlite` (sqlite ships bundled in the Rust crates;
|
|
the system binary is only needed for `kei-brain-view summary`).
|
|
|
|
The installer soft-checks every prereq when it picks the `cortex`
|
|
profile and prints an exact apt/brew/pacman line for anything missing.
|
|
|
|
---
|
|
|
|
## 1. Clone and install
|
|
|
|
```bash
|
|
git clone <your-private-remote-url>/KeiSeiKit && cd KeiSeiKit
|
|
./install.sh --profile=cortex
|
|
```
|
|
|
|
The `cortex` profile provisions exactly the eight primitives listed in
|
|
`_primitives/MANIFEST.toml` — `kei-cortex` (HTTP daemon), `cortex-ui`
|
|
(Svelte 5 + Vite 5 web app), `kei-pet` (persona manifest schema),
|
|
`kei-shared` (DNA + substrate types), `kei-ledger` (SQLite work-unit
|
|
ledger), `kei-memory` (offline session retrospective),
|
|
`frustration-matrix` (longitudinal user-frustration scanner), and
|
|
`kei-skill-importer` (external-format skill importer).
|
|
|
|
Re-run with `--add=kei-tty` if you want the terminal client too.
|
|
|
|
The installer is idempotent — safe to re-run. It never overwrites
|
|
`~/.claude/settings.json` or any user manifest.
|
|
|
|
---
|
|
|
|
## 2. Run the setup wizard
|
|
|
|
In Claude Code (or any AGENTS.md-aware tool that loaded the kit):
|
|
|
|
```
|
|
/cortex-setup
|
|
```
|
|
|
|
Seven phases, mostly clicks. The wizard:
|
|
|
|
- **Phase 0** — detects OS, finds the `kei-cortex` binary path, surfaces
|
|
any missing primitive (hard-fails fast if something didn't install).
|
|
- **Phase 1** — verifies `~/.claude/secrets/.env` has
|
|
`ANTHROPIC_API_KEY`, `ELEVENLABS_API_KEY`, and `FAL_KEY`. For each
|
|
missing key the wizard offers a free-text paste field — never logs
|
|
the value to chat output (RULE 0.8).
|
|
- **Phase 2** — picks port (default `9797`), UI host (default
|
|
`127.0.0.1:18080`), whisper model (`base.en` / `small.en` /
|
|
`medium.en`).
|
|
- **Phase 3** — generates `~/.keisei/cortex.token` (32 hex bytes,
|
|
`chmod 600`).
|
|
- **Phase 4** — `pip install -r scripts/requirements.txt`,
|
|
pre-downloads the chosen whisper model with SHA-256 verification,
|
|
builds the cortex-ui Svelte bundle (`pnpm install && pnpm build`).
|
|
- **Phase 5** — registers a launchd plist on macOS or a systemd user
|
|
unit on Linux. Falls back to `manual` mode if neither supervisor is
|
|
available.
|
|
- **Phase 6** — composes a `setup URL`
|
|
(`http://127.0.0.1:18080/?daemon=…&token=…`), copies it to your
|
|
clipboard, and offers a single click to open it in your default
|
|
browser.
|
|
|
|
Pure-click except for the optional API-key paste fields and the
|
|
optional custom port / UI host. Re-running the wizard is idempotent —
|
|
the token, UI dist, and supervisor unit are preserved.
|
|
|
|
---
|
|
|
|
## 3. Verify the daemon is up
|
|
|
|
```bash
|
|
curl -sS -H "Authorization: Bearer $(cat ~/.keisei/cortex.token)" \
|
|
http://127.0.0.1:9797/healthz
|
|
# Expect: {"ok":true,"version":"0.x.x"}
|
|
```
|
|
|
|
If the daemon is down, `launchctl list | grep keisei` (macOS) or
|
|
`systemctl --user status kei-cortex` (Linux) will tell you why.
|
|
|
|
---
|
|
|
|
## 4. Open the chat
|
|
|
|
The setup URL the wizard copied to your clipboard takes you to the
|
|
Svelte browser app. You'll see:
|
|
|
|
- **Sidebar** — Live2D pet renderer (idle animation, lip-sync to the
|
|
TTS stream), `Setup` / `Dashboard` / `PetEditor` / `LedgerStream` /
|
|
`MemorySearch` routes.
|
|
- **Main pane** — chat panel with PTT (push-to-talk) voice input,
|
|
auto-TTS toggle, optional file-tree + terminal pane.
|
|
- **Top strip** — `BudgetStrip` showing today's Anthropic / ElevenLabs
|
|
/ fal.ai spend pulled from `/usage`.
|
|
|
|
Type a message. The daemon proxies it to Anthropic via
|
|
`/chat` (SSE-streamed tool use), returns the assistant reply, and —
|
|
if auto-TTS is on — pipes the text through `/tts` to ElevenLabs and
|
|
back into the Live2D mouth shape.
|
|
|
|
---
|
|
|
|
## 5. Add the terminal client (optional)
|
|
|
|
```bash
|
|
./install.sh --add=kei-tty
|
|
kei-tty chat
|
|
```
|
|
|
|
Ratatui-based TUI (`_primitives/_rust/kei-tty/src/ui.rs`). Same daemon,
|
|
same token. Use `kei-tty send --message "…"` for a one-shot pipe-friendly
|
|
mode.
|
|
|
|
---
|
|
|
|
## 6. Add the VSCode extension (optional)
|
|
|
|
```bash
|
|
cd _ts_packages/packages/vscode-cortex
|
|
pnpm install && pnpm package
|
|
code --install-extension keisei-cortex-0.1.0.vsix
|
|
```
|
|
|
|
Then `Cmd+Shift+K` (or `Ctrl+Shift+K` on Linux) opens the cortex chat
|
|
view. Right-click any selection to **Ask About Selection** —
|
|
`keisei-cortex.chatAboutSelection` sends the highlighted text into the
|
|
chat panel as context.
|
|
|
|
---
|
|
|
|
## 7. Wire the MCP server (optional)
|
|
|
|
The `kei-mcp` Rust binary (`_primitives/_rust/kei-mcp/`) exposes the
|
|
KeiSeiKit atom registry over the [Model Context
|
|
Protocol](https://modelcontextprotocol.io/). Build it once:
|
|
|
|
```bash
|
|
cd _primitives/_rust && cargo build -p kei-mcp --release
|
|
```
|
|
|
|
Then add to `~/.claude/mcp_servers.json` (or Cline / OpenClaw equivalent
|
|
— see [`_primitives/_rust/kei-mcp/README.md`](../_primitives/_rust/kei-mcp/README.md)
|
|
for all three configs):
|
|
|
|
```json
|
|
{
|
|
"kei": {
|
|
"command": "/abs/path/to/_primitives/_rust/target/release/kei-mcp",
|
|
"args": [],
|
|
"env": {
|
|
"KEI_MCP_ATOMS_ROOT": "/abs/path/to/_primitives/_rust",
|
|
"KEI_MCP_SKILLS_ROOT": "/abs/path/to/skills"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
After a Claude Code reload, every atom under `_primitives/_rust/*/atoms/*.md`
|
|
appears as a callable MCP tool, and every skill under `skills/*/SKILL.md`
|
|
appears as a readable MCP resource.
|
|
|
|
---
|
|
|
|
## What's next
|
|
|
|
- [ARCHITECTURE.md](./ARCHITECTURE.md) — the layer diagram, atoms,
|
|
recipes, frontends, sleep cycle.
|
|
- [SLEEP-LAYER.md](./SLEEP-LAYER.md) — how the nightly Phase A / B / C
|
|
consolidation works.
|
|
- [REFERENCE.md](./REFERENCE.md) — every primitive flag, every hook
|
|
exit code, every skill description.
|
|
- [SECURITY.md](./SECURITY.md) — threat model + mitigations.
|
|
|
|
If anything in this guide doesn't match the repo you're reading,
|
|
that's a bug — please open an issue.
|