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/cookbook.html5Description: Docs — Recipes for real KHAELOR workflows: bug fixes, refactors, model comparisons, nightly maintenance, migrations.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>Cookbook — KHAELOR docs</title>14<meta name="description" content="Recipes for real KHAELOR workflows: bug fixes, refactors, model comparisons, nightly maintenance, migrations.">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>Cookbook</h1>75<p class="lead">Concrete recipes — each one uses the workflow KHAELOR was built around.</p>7677<h2 id="bugfix">Fix a bug, verified<a class="anchor" href="#bugfix">#</a></h2>78<pre><code>khaelor79❯ users report the export button 500s when the list is empty — find it and fix it</code></pre>80<p>KHAELOR explores with <code>symbols</code>/<code>refs</code>/<code>read</code> (understand),81submits a design (a small one auto-approves), edits, and the verify loop runs your typecheck and82tests before it answers. If a test fails, it repairs — bounded to 3 rounds, then an honest report.</p>8384<h2 id="compare">Compare two models on the same task<a class="anchor" href="#compare">#</a></h2>85<pre><code>❯ /replay # type the finished session's id — re-runs its user turns86❯ /model # or switch model first, then /replay87❯ /sdiff # "<idA> <idB>" — turns, tool calls, files, tokens, verify failures</code></pre>88<p>The replay executes inside a throwaway git worktree, so re-run tool calls never touch your89working copy. <em>Run it twice, diff the runs.</em></p>9091<h2 id="parallel">Two features in parallel<a class="anchor" href="#parallel">#</a></h2>92<pre><code>❯ /spawn # "fix the auth bug"93❯ /spawn # "add rate limiting to the API"94❯ /tasks # watch both: phase, diff stats, verify state95❯ /merge # supervised --no-ff merge of each finished branch</code></pre>96<p>Each subtask gets its own worktree, branch (<code>khaelor/<id></code>), and child session97with attenuated permissions. Conflicts abort cleanly; ask KHAELOR to resolve them with both98designs in context.</p>99100<h2 id="nightly">Nightly dependency maintenance<a class="anchor" href="#nightly">#</a></h2>101<pre><code>khaelord goal add "npm deps stay fresh without breaking changes" \102 --type maintain --schedule "0 6 * * 1" \103 --check "npm outdated --json | grep -q ." --escalation draft-pr104khaelord start</code></pre>105<p>Monday 06:00: the cheap <code>check</code> decides whether there is anything to do; a real run106opens a worktree, designs, upgrades, verifies, and leaves a branch for your review. Budget-capped,107fully event-logged.</p>108109<h2 id="branch-experiment">Branch an exploration without losing the thread<a class="anchor" href="#branch-experiment">#</a></h2>110<pre><code>❯ /fork # pick "❯ now add tests" — the fork opens there111# try the risky approach in the fork; the original session is untouched112❯ /sessions # jump back anytime — resume = exact replay</code></pre>113114<h2 id="teach">Teach KHAELOR your project once<a class="anchor" href="#teach">#</a></h2>115<pre><code>❯ our error convention: everything returns Result<T,KError>, never throw in src/core — remember that</code></pre>116<p>The agent persists it via the <code>remember</code> tool into <code>.khaelor/MEMORY.md</code>117with provenance. Every future session starts knowing it. Audit with <code>/memory</code>.</p>118119<h2 id="headless">Headless in CI or scripts<a class="anchor" href="#headless">#</a></h2>120<pre><code>khaelor --print "summarize the churn in src/ since last tag" --gate off121# permission asks resolve to DENY headless — grant what CI needs in .khaelor/config.json</code></pre>122123<h2 id="strict">High-stakes change, strict gate<a class="anchor" href="#strict">#</a></h2>124<pre><code>khaelor --gate strict125❯ migrate the session store from JSON to SQLite</code></pre>126<p>Nothing gets written until you approve the design panel — goal, approach, files, risks,127verification — with a single keystroke.</p>128129<div class="pager">130 <div class="next"><span class="label">Next</span><a href="/docs/usage.html">The TUI →</a></div>131</div>132133</article>134</div></main>135136<footer class="site-footer"><div class="inner">137 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>138 <span>Anthropic-powered · terminal-native by design</span>139</div></footer>140141</body>142</html>143