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<!doctype html>2<!--3KHAELOR4File: website/public/docs/architecture.html5Description: Docs — The small kernel, the services around it, the world seam, and the layering rules that keep KHAELOR honest.6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->9<html lang="en">10<head>11<meta charset="utf-8">12<meta name="viewport" content="width=device-width, initial-scale=1">13<title>Architecture — KHAELOR docs</title>14<meta name="description" content="The small kernel, the services around it, the world seam, and the layering rules that keep KHAELOR honest.">15<link rel="stylesheet" href="/styles.css">16<script>17(function(){try{var t=localStorage.getItem("khaelor-theme");if(!t&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: light)").matches)t="light";if(t==="light")document.documentElement.setAttribute("data-theme","light");}catch(e){}})();18</script>19<script defer src="/site.js"></script>20</head>21<body>2223<header class="site-header"><div class="inner">24 <a class="wordmark" href="/"><span class="glyph">❯</span><span class="g-ember">KHAELOR</span></a>25 <nav>26 <a href="/docs/getting-started.html">Docs</a>27 <a href="/#install">Install</a>28 <button id="theme-toggle" type="button" aria-label="Toggle color theme">light</button>29 </nav>30</div></header>3132<main class="page"><div class="docs-layout">3334<aside class="sidebar">35 <div class="group"><div class="group-title">Start</div>36 <a href="/docs/getting-started.html">Getting started</a>37 <a href="/docs/cookbook.html">Cookbook</a>38 </div>39 <div class="group"><div class="group-title">Using KHAELOR</div>40 <a href="/docs/usage.html">The TUI</a>41 <a href="/docs/commands.html">Commands & keyboard</a>42 <a href="/docs/tools.html">Tools</a>43 <a href="/docs/sessions.html">Sessions</a>44 </div>45 <div class="group"><div class="group-title">Autonomy</div>46 <a href="/docs/phases.html">Phase gates</a>47 <a href="/docs/verification.html">Verification</a>48 <a href="/docs/worktrees.html">Parallel worktrees</a>49 <a href="/docs/daemon.html">The daemon</a>50 </div>51 <div class="group"><div class="group-title">Intelligence</div>52 <a href="/docs/repograph.html">Semantic index</a>53 <a href="/docs/memory.html">Project memory</a>54 <a href="/docs/context.html">Context engine</a>55 <a href="/docs/fork-replay.html">Fork · replay · sdiff</a>56 </div>57 <div class="group"><div class="group-title">Control</div>58 <a href="/docs/permissions.html">Permissions</a>59 <a href="/docs/configuration.html">Configuration</a>60 <a href="/docs/cli.html">CLI reference</a>61 </div>62 <div class="group"><div class="group-title">Internals</div>63 <a href="/docs/architecture.html">Architecture</a>64 <a href="/docs/events.html">The event model</a>65 <a href="/docs/theming.html">Theming & terminal</a>66 </div>67 <div class="group"><div class="group-title">Help</div>68 <a href="/docs/faq.html">FAQ & troubleshooting</a>69 </div>70</aside>7172<article class="content">7374<h1>Architecture</h1>75<p class="lead">One rule above all: <strong>the kernel stays small</strong>. Complexity lives in76services around it — never inside it.</p>7778<h2 id="map">The map<a class="anchor" href="#map">#</a></h2>79<pre><code> KHAELOR TUI ──── khaelord (daemon)80 │ │81 ▼ ▼82 Session Engine (JSONL event log)83 │84 ▼85 Agent Kernel ← deriveNext(state) — a pure fold86 ┌───────────────┼───────────────────┐87 ▼ ▼ ▼88 Context Engine Tool Runtime Model Runtime89 (tiers, cache, (permissions, (Anthropic SDK,90 compaction) phase gate, streaming)91 │ verify loop)92 ▼ ▼93 RepoGraph Workspace ── the ONLY fs/process seam94 Memory │95 Phases Files · Processes · Git worktrees</code></pre>9697<h2 id="kernel">The kernel is a fold<a class="anchor" href="#kernel">#</a></h2>98<p>Each iteration, the kernel re-derives “what next” from the recorded event log — not from99loop-local flags. <code>foldTurnState(events)</code> → <code>deriveNext(state)</code> → dispatch to100a service. Interruption, steering injection, compaction, verification, completion: all are101positions in the log, which is why resume, fork, and replay are cheap and exact.</p>102103<h2 id="services">Services around the kernel<a class="anchor" href="#services">#</a></h2>104<table>105 <tr><th>Service</th><th>Owns</th></tr>106 <tr><td>PhaseService</td><td class="wrap">The gate: per-phase capability policy, design approval, phase events. Consulted by the Tool Runtime — the kernel never sees it.</td></tr>107 <tr><td>VerifyRunner</td><td class="wrap">Native checks after edit batches, the bounded repair loop.</td></tr>108 <tr><td>PermissionService</td><td class="wrap">Capability evaluation (deny > ask > allow), grants, the panel seam.</td></tr>109 <tr><td>ContextEngine</td><td class="wrap">Tiers, byte-stable history projection, prune/compact decisions.</td></tr>110 <tr><td>RepoGraphService</td><td class="wrap">The incremental semantic index behind symbols/refs/skeletons.</td></tr>111 <tr><td>SubtaskManager</td><td class="wrap">Worktree lifecycle, child engines, supervised merges.</td></tr>112 <tr><td>GoalStore / BudgetGuard / ApprovalQueue</td><td class="wrap">The daemon's persistence: goals, ledgers, pending approvals — plain files under <code>.khaelor/daemon/</code>.</td></tr>113</table>114115<h2 id="seams">The seams that matter<a class="anchor" href="#seams">#</a></h2>116<ul>117 <li><strong>Workspace</strong> — four methods (<code>cwd</code>, <code>readFile</code>,118 <code>writeFile</code>, <code>exec</code>); the only module allowed to import119 <code>node:fs</code>/<code>child_process</code>. Everything above it is testable and portable.</li>120 <li><strong>ModelClient</strong> — one streaming interface over the Anthropic SDK. Not a121 multi-provider framework; just a clean wall.</li>122 <li><strong>ChannelAdapter</strong> — daemon notifications (webhook, command today; richer123 channels later without touching the core).</li>124</ul>125126<h2 id="rules">House rules<a class="anchor" href="#rules">#</a></h2>127<ul>128 <li>Every displayed number comes from real data — usage metadata, exit codes, git diffs. No129 fabricated progress, ever.</li>130 <li>Baseline git state is recorded before edits; KHAELOR never assumes an existing diff is its131 own, and never commits unless asked.</li>132 <li>Whenever something is tempted into the kernel, the question is asked: <em>can this be a133 service around it?</em> The answer so far has always been yes.</li>134</ul>135136<div class="pager">137 <div class="next"><span class="label">Next</span><a href="/docs/events.html">The event model →</a></div>138</div>139140</article>141</div></main>142143<footer class="site-footer"><div class="inner">144 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>145 <span>Anthropic-powered · terminal-native by design</span>146</div></footer>147148</body>149</html>150