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/sessions.html5Description: Sessions — persistence, resume, the event log, context compaction, and cost tracking.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>Sessions — KHAELOR</title>14<meta name="description" content="KHAELOR sessions: event-sourced persistence, resume, cost tracking, and context compaction.">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>Sessions</h1>75<p class="lead">Every KHAELOR session is an append-only event log. Nothing is "saved" as an76afterthought — the log <em>is</em> the session, and resume is simply replay.</p>7778<h2 id="event-log">The event log<a class="anchor" href="#event-log">#</a></h2>79<p>Everything that happens flows through a typed event bus and is journaled to a JSONL file as80it happens: your messages, model responses, every tool request, every permission decision,81every file read and modification, process starts and exits, compaction checkpoints. This82design buys you:</p>83<ul>84 <li><strong>Crash safety</strong> — there is no unsaved state to lose; the journal is written85 event by event, atomically.</li>86 <li><strong>Faithful resume</strong> — replaying the log reconstructs the transcript, the87 cost accounting, and the agent's file-state tracking (which files it has read, and whether88 they changed externally since).</li>89 <li><strong>A real audit trail</strong> — for any action KHAELOR ever took, you can90 reconstruct what was requested, which permission rule matched, and who granted it.</li>91 <li><strong>Durable prompts</strong> — a permission request that was pending when you quit92 reappears when you resume. Silence is never treated as consent, even across restarts.</li>93</ul>9495<h2 id="metadata">Session metadata<a class="anchor" href="#metadata">#</a></h2>96<p>Each session carries: id, title (auto-derived from your first request, or set with97<code>/rename</code>), project, created/updated timestamps, model, token usage, cost, git98branch, and working directory. All of it is real recorded data — the costs in the session99picker are the actual API-metered costs.</p>100101<h2 id="managing">Managing sessions<a class="anchor" href="#managing">#</a></h2>102<table>103 <tr><th>Command</th><th>Action</th></tr>104 <tr><td><code>/sessions</code></td><td class="wrap">Browse this project's sessions; <kbd>Enter</kbd> resume, <kbd>n</kbd> new, <kbd>r</kbd> rename, <kbd>x</kbd> delete, <kbd>/</kbd> filter</td></tr>105 <tr><td><code>/resume</code></td><td class="wrap">Resume the most recent session</td></tr>106 <tr><td><code>/new</code></td><td class="wrap">Start a fresh session in the same project</td></tr>107 <tr><td><code>/rename</code></td><td class="wrap">Rename the current session</td></tr>108 <tr><td><code>/clear</code></td><td class="wrap">Clear the conversation and working context</td></tr>109</table>110<pre class="term" data-no-copy><code> ┌─ sessions · ~/dev/my-project ───────────────────────────┐111 <span class="t-accent">❯</span> retry logic in session store <span class="t-dim">12m ago $0.42 main</span>112 context compaction checkpoint <span class="t-dim">2h ago $1.13 main</span>113 initial TUI scaffolding <span class="t-dim">1d ago $2.87 tui/shell</span>114 └────────────────────────────────────────────────────────┘115 <span class="t-dim">↑↓ select · Enter resume · n new · r rename · x delete · / filter · Esc</span></code></pre>116<p>Starting <code>khaelor</code> in a project with an interrupted session adds exactly one117quiet line under the banner — <code>Interrupted session from 12 min ago · /resume to118continue</code> — never an auto-resume, never a modal.</p>119120<h2 id="context">Context management and compaction<a class="anchor" href="#context">#</a></h2>121<p>Long sessions eventually press against the model's context window. KHAELOR watches real122token pressure (the status bar's <code>context 31%</code> segment) and, before the window123becomes dangerous, distills the older conversation into a <strong>structured124checkpoint</strong>:</p>125<pre><code>objective: ...126completed: [...]127current_state: ...128important_files:129 - path: ...130 reason: ...131failed_attempts: [...]132decisions: [...]133running_processes: [...]134next_steps: [...]</code></pre>135<p>Raw evidence that would be destroyed by summarization — exact error messages, key diffs —136is preserved alongside. Compaction is designed to be invisible unless you look:137<code>/context</code> shows the checkpoint and the full token budget breakdown;138<code>/compact</code> triggers it on your schedule. At ≥80% utilization the status bar139nudges you toward <code>/compact</code>; at ≥90% it turns urgent.</p>140141<h2 id="cost">Cost tracking<a class="anchor" href="#cost">#</a></h2>142<p>Every model response's usage metadata — input tokens, output tokens, cache writes, cache143reads — is recorded in the event log as it arrives. <code>/cost</code> aggregates it;144the status bar shows the running total. Two honesty rules:</p>145<ul>146 <li>Numbers come only from actual API usage metadata. KHAELOR never estimates token counts.</li>147 <li>If pricing for your configured model is unknown, you get real token counts and an honest148 <code>n/a</code> in the dollar column — never an invented figure.</li>149</ul>150<p>Cache reads are shown with their hit rate, because prompt-cache health is where most of151your money goes: KHAELOR keeps its prompts byte-stable specifically to maximize cache hits.</p>152153<h2 id="git">Git awareness and protecting your work<a class="anchor" href="#git">#</a></h2>154<ul>155 <li>KHAELOR records the git baseline when the session starts, so <code>/diff</code> shows156 <em>only what KHAELOR changed</em> — your pre-existing uncommitted work is never mixed in or157 attributed to the agent.</li>158 <li>It never auto-commits. Git mutations (<code>commit</code>, <code>push</code>,159 <code>reset</code>, …) go through <a href="/docs/permissions.html">permissions</a> and160 default to <code>ask</code>.</li>161 <li>Files you edit outside KHAELOR while a session runs are protected by162 external-modification detection — the agent must re-read before touching them.</li>163</ul>164165<h2 id="fork">Fork, replay, sdiff<a class="anchor" href="#fork">#</a></h2>166<p>Because resume is a replay of the JSONL, three operations come almost for free — and turn167sessions into a comparison instrument no other CLI agent offers:</p>168<table>169 <tr><th>Command</th><th>What it does</th></tr>170 <tr><td><code>/fork</code></td><td class="wrap">Pick a checkpoint (any user turn, approved design, or context checkpoint) and branch the session there. The JSONL prefix is copied into a fresh session with a <code>meta.json</code> recording <code>parent</code> and <code>forkPoint</code>; KHAELOR opens the fork immediately.</td></tr>171 <tr><td><code>/replay</code></td><td class="wrap">Re-run another session's <em>user turns</em> with the current model, inside a throwaway git worktree so re-executed tool calls have zero side effects on your working copy.</td></tr>172 <tr><td><code>/sdiff</code></td><td class="wrap">Structured diff between two runs: agent turns, tool calls, files modified, tokens in/out, cache reads, verify failures, outcome — plus which files each run touched exclusively.</td></tr>173</table>174<pre class="term" data-no-copy><code> <span class="t-b">sdiff</span>175 <span class="t-dim">01J8K2… (sonnet)</span> <span class="t-dim">01J8K9… (haiku)</span>176 agent turns 12 17177 tool calls 34 61178 files modified 2 3179 tokens (in/out) 145.0k / 12.0k 210.0k / 19.0k180 verify failures 0 2181 outcome completed completed182 <span class="t-dim">files only in B: src/c.ts</span></code></pre>183<p><em>Run it twice, diff the runs</em> — the cheapest honest model comparison you can do.</p>184185<h2 id="storage">Where sessions live<a class="anchor" href="#storage">#</a></h2>186<p>Session logs are stored under <code>~/.khaelor/sessions/</code> as plain JSONL — one event187per line, inspectable with standard tools. Associated artifacts (spilled tool output, process188logs) live beside them under <code>~/.khaelor/tool-output/</code> and189<code>~/.khaelor/process-logs/</code>, garbage-collected when sessions are deleted and capped190in total size. Deleting a session from <code>/sessions</code> removes its log and artifacts.</p>191192<div class="pager">193 <div><span class="label">Previous</span><a href="/docs/configuration.html">← Configuration</a></div>194 <div class="next"><span class="label">Next</span><a href="/docs/faq.html">FAQ →</a></div>195</div>196197</article>198</div></main>199200<footer class="site-footer"><div class="inner">201 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>202 <span>Anthropic-powered · terminal-native by design</span>203</div></footer>204205</body>206</html>207