spb/khaelor Public
KHAELOR — a terminal-native autonomous engineering agent powered by Anthropic.
TypeScript 82.9%
HTML 14.9%
CSS 1.1%
JavaScript 0.7%
1<!--2KHAELOR3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78<div align="center">910```11██╗ ██╗██╗ ██╗ █████╗ ███████╗██╗ ██████╗ ██████╗12██║ ██╔╝██║ ██║██╔══██╗██╔════╝██║ ██╔═══██╗██╔══██╗13█████╔╝ ███████║███████║█████╗ ██║ ██║ ██║██████╔╝14██╔═██╗ ██╔══██║██╔══██║██╔══╝ ██║ ██║ ██║██╔══██╗15██║ ██╗██║ ██║██║ ██║███████╗███████╗╚██████╔╝██║ ██║16╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚══════╝ ╚═════╝ ╚═╝ ╚═╝17```1819### The autonomous engineer whose every decision you can replay, fork, and diff.2021[](https://www.khaelor.sh)22[](#development)23[](package.json)24[](https://www.anthropic.com)2526[](https://www.khaelor.sh/docs/theming.html)27[](https://www.khaelor.sh/docs/events.html)28[](https://www.khaelor.sh/docs/phases.html)29[](https://www.khaelor.sh/docs/verification.html)30[](#the-honesty-contract)3132**[Website](https://www.khaelor.sh)** · **[Docs](https://www.khaelor.sh/docs/getting-started.html)** · **[Cookbook](https://www.khaelor.sh/docs/cookbook.html)** · **[The daemon](https://www.khaelor.sh/docs/daemon.html)** · **[Architecture](https://www.khaelor.sh/docs/architecture.html)**3334</div>3536---3738KHAELOR is **not** another coding-agent clone. It designs before it implements, verifies before it39claims done, and writes every action — even the ones at 3 AM — into an append-only log you can40audit. **Autonomy without auditability is scary. KHAELOR ships auditable autonomy.**4142```43Understand first. Design second. Implement third. Verify always — even at 3 AM.44```4546## ⚡ Install4748```sh49curl -fsSL https://www.khaelor.sh/install.sh | sh # hosted installer50# or51npm install -g khaelor52```5354```sh55export ANTHROPIC_API_KEY=sk-ant-...56cd your-project57khaelor58```5960## 🔥 What a session looks like6162```63 KHAELOR ▸ my-project · main6465 ❯ fix the memory leak in the renderer6667 ├─ symbols "RenderBuffer" · 3 hits · 12ms68 ├─ refs appendLine · callers · 14 sites69 ╰─ read src/tui/render.ts · 240 lines7071 ◑ design submitted · 2 files · replace growing buffer with a ring72 ✓ design auto-approved · 2 files7374 ├─ edit src/tui/render.ts +31 −1275 ╰─ edit src/tui/buffer.ts +8 −37677 ⟳ verify typecheck ✓ 1.2s · tests ✓ 4.1s · lint ✓78 ✓ verified 4.1s7980 ● IMPLEMENT ─ main │ sonnet │ ▰▰▰▱▱▱▱▱ 38% │ in 45k · out 3.2k81```8283## 🏛️ Six things no other CLI agent does together8485| | Feature | The point |86|---|---|---|87| ◐◑● | **[Phase gates](https://www.khaelor.sh/docs/phases.html)** | "Understand → design → implement" is a *runtime mechanism*. Write tools stay locked until a design artifact is approved. `--gate strict\|auto\|off` |88| ⟳ | **[Native verification](https://www.khaelor.sh/docs/verification.html)** | After each edit batch KHAELOR runs *your* typecheck/tests/lint itself and repairs failures in a bounded loop — before handing back |89| ⑂ | **[Fork · replay · sdiff](https://www.khaelor.sh/docs/fork-replay.html)** | `/fork` any checkpoint. `/replay` a run with another model in a throwaway worktree. `/sdiff` the two runs. *Run it twice, diff the runs* |90| ◈ | **[Semantic index](https://www.khaelor.sh/docs/repograph.html)** | `symbols` finds definitions with signatures; `refs` maps callers/callees/importers before an edit. Skeletons instead of whole files |91| ✎ | **[Memory with provenance](https://www.khaelor.sh/docs/memory.html)** | The agent maintains `.khaelor/MEMORY.md` itself — every entry anchored to the exact session + event that produced it |92| ⇄ | **[Parallel worktrees](https://www.khaelor.sh/docs/worktrees.html)** | `/spawn` subtasks in isolated git worktrees with attenuated capabilities. Supervised `--no-ff` merges. Your working copy is never touched |9394## 🌙 khaelord — the engineer that lives9596A persistent daemon with **structured, event-sourced goals** — not a prose checklist:9798```sh99khaelord goal add "keep npm deps fresh without breaking changes" \100 --type maintain --schedule "0 6 * * 1" --budget 5 --escalation draft-pr101khaelord start102```103104```105 03:12 ● goal deps-fresh check failed → run r7f2 in worktree khaelor/goal-r7f2106 03:14 ◑ design recorded · 3 files · in the log, replayable107 03:17 ✓ verified · typecheck ✓ tests ✓ · branch left for review108 03:17 spent today: $1.84 / $20 · runs 1/8109```110111Every run: throwaway worktree → phase gates (even at night) → mandatory verification → hard budget112ceilings → async approval queue (a suspended run costs **zero**). Every decision: one line in an113event log you can replay the next morning. **[→ The daemon](https://www.khaelor.sh/docs/daemon.html)**114115## 🧾 The honesty contract116117| | |118|---|---|119| Costs & tokens | summed from **real API usage metadata** — never estimated, never invented |120| Test results | your own commands, real exit codes, errors-first truncation |121| History | append-only JSONL, torn-write recovery, **byte-exact replay** |122| Permissions | capability-based, deny > ask > allow — **silence is never consent** |123| 3 AM decisions | one event log per goal run — `Enter` replays exactly what happened |124125## 🎛️ Inside the TUI126127```128/phase /verify /fork /replay /sdiff /memory /spawn /tasks /merge /goals ← v2129/model /config /permissions /context /sessions /resume /new /compact130/cost /status /diff /processes /help /quit131```132133- `Ctrl+K` universal palette · `@` fuzzy file mentions · `!cmd` shell mode · `Esc` interrupt134- **Type while it works** — steering messages queue and inject at a safe seam135- Theme **khaelis** (obsidian + magma), OKLCH gradients, truecolor → 256 → 16 → mono ladder136- `khaelor --doctor-tui` prints detected capabilities *with reasons* · `--splash` for the opening moment137138<details>139<summary><b>🏗️ Architecture — a deliberately small kernel</b></summary>140141```142 KHAELOR TUI ──── khaelord (daemon)143 │ │144 ▼ ▼145 Session Engine (JSONL event log)146 │147 ▼148 Agent Kernel ← deriveNext(state) — a pure fold149 ┌───────────────┼───────────────────┐150 ▼ ▼ ▼151 Context Engine Tool Runtime Model Runtime152 (tiers, cache, (permissions, (Anthropic SDK,153 compaction) phase gate, streaming)154 │ verify loop)155 ▼ ▼156 RepoGraph Workspace ── the ONLY fs/process seam157 Memory │158 Phases Files · Processes · Git worktrees159```160161- **40 durable event types** — everything is a fold over the log: the conversation, the costs,162 the diffs, the phases, even "what should happen next"163- **11 tools** — read · write · edit (9-strategy replacer) · grep · glob · bash · process ·164 **design · remember · symbols · refs**165- **Custom ANSI renderer** — print-once scrollback, bounded live region, 16 ms coalesced frames,166 sub-millisecond input latency167- Design docs in [`docs/`](docs/) · v2 notes in [`docs/V2_IMPLEMENTATION.md`](docs/V2_IMPLEMENTATION.md)168169</details>170171<details>172<summary><b>🧪 Development</b></summary>173174```sh175npm install176npm run check # typecheck + eslint + 698 tests + mandatory header check177npm run dev # run from source178npx tsx src/tui/demo.ts # TUI demo with mocked model events179node website/server.mjs # the docs site, locally180```181182V1/V2 are Anthropic-only by design. The model layer is isolated behind a single `ModelClient`183interface — clean architecture, not a provider framework.184185</details>186187---188189<div align="center">190191**[www.khaelor.sh](https://www.khaelor.sh)** — *run it twice, diff the runs.*192193Simon-Pierre Boucher · [contact@spboucher.ai](mailto:contact@spboucher.ai)194195</div>196