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/daemon.html5Description: Docs — khaelord: event-sourced goals, heartbeat, budget guard, approvals, channels (v2 §7).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>The daemon (khaelord) — KHAELOR docs</title>14<meta name="description" content="khaelord runs KHAELOR autonomously: structured event-sourced goals, throwaway worktrees, phase gates at 3 AM, hard budget ceilings, async approvals, and channels.">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>The daemon — <code>khaelord</code></h1>75<p class="lead">The long-term autonomous mode: an engineer that lives in your project, whose every76decision — even at 3 AM — is an event you can replay the next morning.</p>7778<h2 id="model">The model<a class="anchor" href="#model">#</a></h2>79<p>Where other always-on agents keep a prose checklist, KHAELOR has <strong>structured,80event-sourced goals</strong>. Each goal run:</p>81<ol>82 <li>opens an isolated session in a <strong>throwaway git worktree</strong> — the daemon never touches your working copy;</li>83 <li>runs with <strong>phase gates in auto mode</strong> — the design artifact lands in the log even at night;</li>84 <li>runs <strong>mandatory verification</strong> — no escalation when typecheck or tests fail;</li>85 <li>appends every event to <code>.khaelor/daemon/goals/<id>.events.jsonl</code> — replayable, auditable.</li>86</ol>8788<h2 id="goals">Goals<a class="anchor" href="#goals">#</a></h2>89<pre><code>khaelord goal add "watch GitHub issues labeled 'bug', reproduce, propose a fix" \90 --type watch --schedule "*/30 * * * *" --budget 5 --escalation draft-pr9192khaelord goal add "npm deps stay fresh without breaking changes" \93 --type maintain --schedule "0 6 * * 1" --check "npm outdated --json | grep -q ." \94 --escalation draft-pr9596khaelord goal list97khaelord goal pause <id> · khaelord goal resume <id></code></pre>98<table>99 <tr><th>Field</th><th>Meaning</th></tr>100 <tr><td><code>--type</code></td><td class="wrap"><code>maintain</code> (keep an invariant), <code>achieve</code> (reach a state), <code>watch</code> (react to signals).</td></tr>101 <tr><td><code>--schedule</code></td><td class="wrap">A cron expression, or <code>heartbeat</code> to ride the daemon tick (default every 30 min).</td></tr>102 <tr><td><code>--check</code></td><td class="wrap">Cheap triage: a command whose exit code decides if there is anything to do. Exit 0 → the run is skipped and logged as such. This is the two-tier cost routing: the check is (nearly) free, the strong model only runs when there is real work.</td></tr>103 <tr><td><code>--budget</code></td><td class="wrap">USD/day ceiling for this goal (with configured pricing) plus <code>--runs</code> runs/day.</td></tr>104 <tr><td><code>--escalation</code></td><td class="wrap"><code>notify</code> · <code>draft-pr</code> (branch left for review) · <code>auto-merge-if-verified</code> (--no-ff merge only when every check passed).</td></tr>105</table>106107<h2 id="running">Running it<a class="anchor" href="#running">#</a></h2>108<pre><code>khaelord start # foreground; use nohup / launchd / systemd to detach109khaelord status # pid, active runs, spent today110khaelord stop</code></pre>111<pre class="term" data-no-copy><code> <span class="t-dim">03:12</span> <span class="t-ember">●</span> goal <span class="t-teal">deps-fresh</span> check failed → run r7f2 <span class="t-dim">in worktree khaelor/goal-r7f2</span>112 <span class="t-dim">03:14</span> <span class="t-ember">◑</span> design recorded <span class="t-dim">· 3 files</span>113 <span class="t-dim">03:17</span> <span class="t-ok">✓ verified</span> · branch khaelor/goal-r7f2 left for review <span class="t-dim">(escalation: draft-pr)</span>114 <span class="t-dim">03:17 spent today: $1.84 / $20 · runs 1/8</span></code></pre>115116<h2 id="budget">Budget guard<a class="anchor" href="#budget">#</a></h2>117<pre><code>// .khaelor/daemon/config.json118{119 "budget": { "maxUsdPerDay": 20, "maxUsdPerRun": 3, "hardStop": true },120 "activeHours": "07:00-23:00",121 "heartbeatMinutes": 30,122 "model": { "runs": "claude-sonnet-4-5" },123 "channels": { "webhook": "https://…", "command": "./notify.sh" },124 "pricing": { "inputPerMTok": 3, "outputPerMTok": 15, "cacheReadPerMTok": 0.3, "cacheWritePerMTok": 3.75 }125}</code></pre>126<p>Ceilings are hard: once a goal or the daemon hits its daily budget, runs are skipped and the skip127is logged. Costs are computed from <strong>real API usage</strong> and only when pricing is128configured — KHAELOR never invents a dollar figure. Without pricing, <code>maxRunsPerDay</code>129is the binding limit.</p>130131<h2 id="approvals">Asynchronous approvals<a class="anchor" href="#approvals">#</a></h2>132<p>When a run needs a permission at 3 AM, it does not block and does not burn tokens waiting:133the request lands in a persisted queue, the run checkpoints (a paused run is just a paused JSONL —134it costs zero), and the daemon moves to the next goal.</p>135<pre><code>khaelord approvals # list pending requests with context136khaelord approve <id> # or: khaelord deny <id></code></pre>137138<h2 id="channels">Channels<a class="anchor" href="#channels">#</a></h2>139<p>V1 ships two adapters behind one <code>ChannelAdapter</code> seam — the same philosophy as the140isolated <code>ModelClient</code>:</p>141<ul>142 <li><strong>webhook</strong> — every notification POSTed as JSON;</li>143 <li><strong>command</strong> — notifications piped to a script's stdin: plug in mail, Slack, ntfy, whatever you like.</li>144</ul>145146<h2 id="audit">Auditability<a class="anchor" href="#audit">#</a></h2>147<p>In the TUI, <code>/goals</code> shows every goal, its schedule, and today's spend. Each run148references its child session id — resume it, <code>/fork</code> it, or <code>/sdiff</code> it149against another run. <em>Autonomy without auditability is scary; KHAELOR's autonomy is auditable150by construction.</em></p>151152<div class="pager">153 <div><span class="label">Previous</span><a href="/docs/phases.html">← Phase gates & verify</a></div>154 <div class="next"><span class="label">Next</span><a href="/docs/permissions.html">Permissions →</a></div>155</div>156157</article>158</div></main>159160<footer class="site-footer"><div class="inner">161 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>162 <span>Anthropic-powered · terminal-native by design</span>163</div></footer>164165</body>166</html>167