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/usage.html5Description: The TUI in depth — composer, file mentions, shell mode, interruption, steering, tool presentation.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 TUI — KHAELOR</title>14<meta name="description" content="KHAELOR's terminal interface in depth: composer, multiline editing, @ file mentions, ! shell mode, Esc interruption, steering while the agent works.">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>KHAELOR</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 </div>38 <div class="group"><div class="group-title">Using KHAELOR</div>39 <a href="/docs/usage.html">The TUI</a>40 <a href="/docs/commands.html">Commands & keyboard</a>41 <a href="/docs/tools.html">Tools</a>42 <a href="/docs/sessions.html">Sessions</a>43 </div>44 <div class="group"><div class="group-title">Control</div>45 <a href="/docs/permissions.html">Permissions</a>46 <a href="/docs/configuration.html">Configuration</a>47 </div>48 <div class="group"><div class="group-title">Help</div>49 <a href="/docs/faq.html">FAQ & troubleshooting</a>50 </div>51</aside>5253<article class="content">5455<h1>The TUI</h1>56<p class="lead">KHAELOR is not a <code>> prompt / AI: response</code> REPL. It is a modern57interactive computing environment built for the terminal — and this page is how to drive it.</p>5859<h2 id="layout">How the screen works<a class="anchor" href="#layout">#</a></h2>60<p>KHAELOR renders into your terminal's <strong>normal scrollback</strong>, like a well-behaved61CLI — not a full-screen alternate-screen app. Two zones:</p>62<ul>63 <li><strong>Settled content</strong> — finished messages, completed tool rows, your submitted64 prompts. Printed exactly once, never touched again. Native selection, copy, and terminal65 search work on all of it, and the transcript survives even if KHAELOR crashes.</li>66 <li><strong>Live region</strong> — a small strip pinned to the bottom (at most ~24 rows): the67 streaming tail of the current response, one agent status line, the composer, and the status68 bar. It is the only thing that ever repaints, in flicker-free synchronized frames.</li>69</ul>70<p>Consequences you will feel: no scroll jumps, no flicker, no layout destruction from long71output, and typing latency that stays under 16 ms even while the model streams at full72rate. If you scroll up to read something, nothing yanks you back down — new content73accumulates below, exactly like <code>tail -f</code>.</p>74<p>The one full-screen exception is the <a href="/docs/commands.html#diff-viewer"><code>/diff</code>75viewer</a>, which behaves like <code>less</code>: enter, navigate, <kbd>q</kbd>, and your76conversation is untouched.</p>7778<h2 id="composer">The composer<a class="anchor" href="#composer">#</a></h2>79<p>The input line is a real editor, not a bare readline:</p>80<pre class="term" data-no-copy><code> <span class="t-accent">❯</span> refactor <span class="t-accent">@src/session/store.ts</span> to journal events atomically,81 then run the tests</code></pre>8283<h3 id="multiline">Multiline editing</h3>84<ul>85 <li><kbd>Enter</kbd> submits. <kbd>Shift+Enter</kbd> or <kbd>Ctrl+J</kbd> inserts a newline86 (<kbd>Shift+Enter</kbd> works in terminals with the kitty keyboard protocol or87 modifyOtherKeys; <kbd>Ctrl+J</kbd> works everywhere; a trailing <code>\</code> before88 <kbd>Enter</kbd> also continues the line).</li>89 <li>The composer grows from one row up to a third of the screen, then scrolls internally.</li>90 <li>Full cursor movement: characters (<kbd>←</kbd>/<kbd>→</kbd>,91 <kbd>Ctrl+B</kbd>/<kbd>Ctrl+F</kbd>), words (<kbd>Alt+←/→</kbd>,92 <kbd>Alt+B</kbd>/<kbd>Alt+F</kbd>), line start/end (<kbd>Ctrl+A</kbd>/<kbd>Ctrl+E</kbd>),93 lines (<kbd>↑</kbd>/<kbd>↓</kbd> inside a multiline buffer).</li>94 <li>Deletion: word back <kbd>Ctrl+W</kbd>/<kbd>Alt+Backspace</kbd>, word forward95 <kbd>Alt+D</kbd>, to line start <kbd>Ctrl+U</kbd>. Undo with <kbd>Ctrl+_</kbd>.</li>96 <li><kbd>Ctrl+G</kbd> round-trips the whole buffer through <code>$EDITOR</code> for heavy97 editing, then returns it to the composer.</li>98</ul>99100<h3 id="history">History</h3>101<p>Prompt history is per-project (50 entries, deduplicated, stored in102<code>~/.khaelor/prompt-history.jsonl</code>). <kbd>↑</kbd> at the start of the buffer and103<kbd>↓</kbd> at the end navigate it — cursor-position-aware, so history never hijacks104multiline editing. <kbd>Ctrl+R</kbd> opens incremental history search.</p>105106<h3 id="paste">Paste intelligence</h3>107<p>Bracketed paste is handled structurally. A paste of three or more lines (or >150108characters) collapses into a compact span — <code>◫ pasted 47 lines</code> — that expands109only at submit, so a big stack trace never wrecks your editing view. A paste that looks like a110file path becomes a file mention automatically.</p>111112<h2 id="mentions">@ file mentions<a class="anchor" href="#mentions">#</a></h2>113<p>Type <code>@</code> anywhere to fuzzy-search the repository (respecting114<code>.gitignore</code> and <code>.khaelorignore</code>), ranked by match quality and115frecency — files you touch often float to the top:</p>116<pre class="term" data-no-copy><code> <span class="t-accent">❯</span> refactor @agent117 ┌────────────────────────────────────────┐118 src/kernel/agent.ts <span class="t-warn">★</span>119 src/agents/agent-runtime.ts120 tests/agent.test.ts121 └────────────────────────────────────────┘</code></pre>122<p>Selecting inserts a <strong>structured file reference</strong> — the agent's context engine123receives a reference to resolve intelligently, not a blind dump of the file's contents. Line124ranges are supported in the syntax: <code>@src/kernel/agent.ts:40-90</code>.</p>125126<h2 id="shell-mode">! shell mode<a class="anchor" href="#shell-mode">#</a></h2>127<p>Type <code>!</code> as the first character to run a shell command yourself, without128involving the model:</p>129<pre class="term" data-no-copy><code> <span class="t-warn">!</span> git status --short130131 <span class="t-dim">$ git status --short</span>132 M src/session/store.ts133 ?? notes.md134 <span class="t-dim">a — add output to context</span></code></pre>135<p>The prompt glyph switches to <code>!</code> (warning tint). Output prints into the136conversation as a settled block; press <kbd>a</kbd> immediately after to hand that output to137the agent as context — it never enters the model's context without your say-so. Shell mode138runs under the same <a href="/docs/permissions.html">permission rules</a> as the agent's own139<code>bash</code> tool.</p>140141<h2 id="status">Knowing what the agent is doing<a class="anchor" href="#status">#</a></h2>142<p>One compact status line above the composer tracks the agent's real state —143<em>thinking · reading · searching · editing · running ·144waiting · verifying · idle</em>:</p>145<pre class="term" data-no-copy><code> <span class="t-accent">●</span> Searching repository <span class="t-dim">· 2.3s</span>146 <span class="t-accent">●</span> Editing src/kernel/agent.ts147 <span class="t-accent">●</span> Running npm test <span class="t-dim">· 41/148</span>148 <span class="t-accent">●</span> Waiting for permission</code></pre>149<p>Every element is real data: elapsed time is a real timer; counts like <code>41/148</code>150appear only when a tool's output actually contained them. There are no fake spinners and no151invented percentages, ever. When idle, the line disappears entirely.</p>152153<h3 id="tool-rows">Tool call presentation</h3>154<p>Each tool call settles into one collapsed line — enough to audit, quiet enough to ignore:</p>155<pre class="term" data-no-copy><code> <span class="t-dim">▸</span> Read <span class="t-b">src/kernel/agent.ts</span> <span class="t-dim">· 212 lines</span>156 <span class="t-dim">▸</span> Search <span class="t-b">"ContextEngine"</span> <span class="t-dim">· 14 matches</span>157 <span class="t-dim">▸</span> Edit <span class="t-b">src/context/engine.ts</span> <span class="t-dim">· +31 −12</span>158 <span class="t-dim">▸</span> Run <span class="t-b">npm test</span> <span class="t-dim">·</span> <span class="t-ok">passed</span> <span class="t-dim">· 4.2s</span></code></pre>159<ul>160 <li><kbd>Ctrl+T</kbd> cycles detail on the currently-running tool (collapsed ↔ a rolling161 12-line tail of its output).</li>162 <li><kbd>d</kbd> (with an empty composer) prints the diff of the most recent edit.</li>163 <li>Very long output is truncated head/tail with an explicit marker; the full output is saved164 to a file whose path is shown — nothing is silently lost.</li>165</ul>166167<h2 id="interruption">Interruption — <kbd>Esc</kbd><a class="anchor" href="#interruption">#</a></h2>168<p>Press <kbd>Esc</kbd> at any moment. Acknowledgment is immediate — the status line flips to169<code>◎ Stopping…</code> in the same frame — then cancellation propagates cleanly170through the model stream, any in-flight tools, and the agent loop:</p>171<pre class="term" data-no-copy><code> <span class="t-dim">▸</span> Run <span class="t-b">npm test</span> <span class="t-dim">· cancelled · 3.2s</span>172 <span class="t-dim">◎ Interrupted — partial response kept</span></code></pre>173<p>The session is never corrupted by an interrupt: partial output is kept and marked, and174background processes you started (dev servers, watchers) are deliberately left running.175<kbd>Esc</kbd> with an overlay open closes the overlay instead; with text in an idle composer176it clears the current completion/selection first.</p>177178<h2 id="steering">Steering while the agent works<a class="anchor" href="#steering">#</a></h2>179<p>The composer never locks. Type while the agent is mid-task and press <kbd>Enter</kbd> —180your message is queued and injected at the next safe boundary between tool calls:</p>181<pre class="term" data-no-copy><code> <span class="t-dim">▸</span> Run <span class="t-b">npm test</span> <span class="t-dim">· running 8s</span>182183 <span class="t-warn">⋯</span> Queued — use the smaller fixture instead184 <span class="t-dim">Esc cancel run · Ctrl+U discard queued</span></code></pre>185<p>Queued messages show with the <code>⋯</code> marker until injected, then settle into the186transcript as normal user messages. Multiple queued messages stack in order. <kbd>Ctrl+U</kbd>187with an empty composer discards the most recent queued message. This is how you course-correct188without killing a run: <em>"skip the lint step"</em>, <em>"target Node 22"</em>,189<em>"that file is generated, edit the template instead"</em>.</p>190191<h2 id="statusbar">The status bar<a class="anchor" href="#statusbar">#</a></h2>192<p>One dim row at the very bottom — persistent, never animated:</p>193<pre class="term" data-no-copy><code> <span class="t-dim">main +4 −1 │ claude-sonnet-4-5 │ context 31% │ $0.42 │ ● 2</span></code></pre>194<table>195 <tr><th>Segment</th><th>Meaning</th></tr>196 <tr><td><code>main +4 −1</code></td><td class="wrap">Git branch and dirty-file counts, live.</td></tr>197 <tr><td><code>claude-sonnet-4-5</code></td><td class="wrap">The session's model (shortens to an alias on narrow terminals).</td></tr>198 <tr><td><code>context 31%</code></td><td class="wrap">Real context-window utilization. At ≥80% it tints and suggests <code>/compact</code>.</td></tr>199 <tr><td><code>$0.42</code></td><td class="wrap">Session cost from actual API usage metadata.</td></tr>200 <tr><td><code>● 2</code></td><td class="wrap">Running background processes.</td></tr>201 <tr><td><code>⋯ 1 queued</code></td><td class="wrap">Queued steering messages, when any.</td></tr>202</table>203<p>Segments with no real data are absent, not zeroed. On narrow terminals, lower-priority204segments drop whole rather than truncating.</p>205206<h2 id="accessibility">Color, monochrome, accessibility<a class="anchor" href="#accessibility">#</a></h2>207<ul>208 <li>One calm default theme (dark), with an automatic light variant when your terminal209 background is detected as light.</li>210 <li><code>NO_COLOR</code> and <code>TERM=dumb</code> are honored absolutely. State is never211 conveyed by color alone — every state pairs a symbol or a word: <code>✓</code> done,212 <code>▸</code> tool, <code>●</code>/<code>○</code> running/stopped,213 <code>⋯</code> queued, <code>◎</code> interrupted, <code>failed</code>/<code>passed</code>214 spelled out.</li>215 <li>Keyboard-only use is complete — there is nothing that requires a mouse.</li>216</ul>217218<div class="pager">219 <div><span class="label">Previous</span><a href="/docs/getting-started.html">← Getting started</a></div>220 <div class="next"><span class="label">Next</span><a href="/docs/commands.html">Commands & keyboard →</a></div>221</div>222223</article>224</div></main>225226<footer class="site-footer"><div class="inner">227 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>228 <span>Anthropic-powered · terminal-native by design</span>229</div></footer>230231</body>232</html>233