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/tools.html5Description: The seven agent tools explained for users — capabilities, output, truncation, and background processes.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>Tools — KHAELOR</title>14<meta name="description" content="The seven tools KHAELOR's agent uses: read, write, edit, grep, glob, bash, and process — plus how output truncation and background processes behave.">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>Tools</h1>75<p class="lead">KHAELOR gives the model exactly <strong>seven</strong> powerful primitives —76not dozens of micro-tools. Every tool call is permission-checked before it runs, rendered as a77compact one-liner in the conversation, and journaled in the session's event log.</p>7879<table>80 <tr><th>Tool</th><th>What it does</th><th>You see</th></tr>81 <tr><td><code>read</code></td><td class="wrap">Read a file (paged, line-numbered)</td><td class="wrap"><code>▸ Read src/kernel/agent.ts · lines 1–2000 of 3417</code></td></tr>82 <tr><td><code>write</code></td><td class="wrap">Create or fully replace a file</td><td class="wrap"><code>▸ Write src/context/budget.ts · new file · 114 lines</code></td></tr>83 <tr><td><code>edit</code></td><td class="wrap">Surgical in-place replacement</td><td class="wrap"><code>▸ Edit src/context/engine.ts · +31 −12</code></td></tr>84 <tr><td><code>grep</code></td><td class="wrap">Content search (ripgrep)</td><td class="wrap"><code>▸ Search "ContextEngine" · 14 matches in 5 files</code></td></tr>85 <tr><td><code>glob</code></td><td class="wrap">Find files by name pattern</td><td class="wrap"><code>▸ Glob src/**/*.ts · 23 files</code></td></tr>86 <tr><td><code>bash</code></td><td class="wrap">Run a short-lived shell command</td><td class="wrap"><code>▸ Run npm test · exit 0 · 3.2s</code></td></tr>87 <tr><td><code>process</code></td><td class="wrap">Manage background processes</td><td class="wrap"><code>▸ Process start npm run dev · p3 running</code></td></tr>88</table>8990<p>There is deliberately no <code>git</code> tool — git flows through <code>bash</code> under91the same permission rules, where you can see and gate every command.</p>9293<h2 id="read"><code>read</code><a class="anchor" href="#read">#</a></h2>94<p>Reads files with line numbers, up to 2,000 lines per page; the output always states the95total and how to continue, so the agent pages through large files instead of dumping them.96Guard rails you benefit from:</p>97<ul>98 <li><strong>Binary detection</strong> — binary files are described (type, size), never dumped as bytes.</li>99 <li><strong>Size guard</strong> — files over 10 MB are refused with guidance to search or page instead.</li>100 <li><strong>Near-miss suggestions</strong> — a typo'd path gets "Did you mean…?" candidates from the repository index.</li>101 <li><strong>Directories</strong> — reading a directory lists its entries instead of erroring.</li>102</ul>103<p>Every successful read is also recorded in the session's file registry — this is what powers104the safety rule that the agent must <em>read before it writes</em> (below).</p>105106<h2 id="write"><code>write</code><a class="anchor" href="#write">#</a></h2>107<p>Writes a complete file, creating parent directories as needed. Two protections guard your108work on existing files:</p>109<ul>110 <li><strong>Read-before-write</strong> — the agent cannot overwrite a file it has not read in111 this session. It is structurally impossible for it to blow away content it never saw.</li>112 <li><strong>External-modification detection</strong> — if the file changed on disk after the113 agent last read it (you edited it, or another process did), the write is refused and the114 agent must re-read and reapply. Your concurrent edits are never clobbered.</li>115</ul>116<p>Writes are atomic (temp file + fsync + rename), preserve line endings (CRLF), BOM, and file117mode bits. Every write produces a unified diff you can expand instantly with <kbd>d</kbd> or118review in <code>/diff</code>.</p>119120<h2 id="edit"><code>edit</code><a class="anchor" href="#edit">#</a></h2>121<p>The most important tool: exact string replacement inside a file. The agent supplies the text122to find and its replacement; KHAELOR requires the match to be <strong>unambiguous</strong>.123Under the hood, a nine-strategy matching cascade makes edits robust without making them124reckless:</p>125<ol>126 <li>Exact match</li>127 <li>Line-trimmed match (whitespace drift at line edges)</li>128 <li>Whitespace-normalized match</li>129 <li>Indentation-flexible match (block quoted at the wrong indent depth — the file's real indentation is preserved)</li>130 <li>Escape-normalized match (over-escaped <code>\n</code>, <code>\t</code>, quotes)</li>131 <li>Trimmed-boundary match</li>132 <li>Block-anchor fuzzy match (first/last lines as anchors, similarity-scored middle)</li>133 <li>Context-aware fuzzy match (last resort)</li>134 <li>Multi-occurrence replace-all (exact matches only — fuzzy mass-replace is never allowed)</li>135</ol>136<p>The guards matter as much as the strategies: an ambiguous match (multiple locations) fails137with the line numbers instead of silently picking one; a fuzzy match that would replace a138disproportionately large region is refused. Failed edits return precise repair guidance to the139model — the closest near-miss with the exact line and character difference — so the agent140fixes itself instead of thrashing. Same read-before-edit and external-modification protection141as <code>write</code>; same instant diff.</p>142143<h2 id="grep"><code>grep</code><a class="anchor" href="#grep">#</a></h2>144<p>Fast regex content search over the repository, powered by ripgrep (bundled — no system145dependency). Results are grouped by file with line numbers, ordered by most recently modified,146and hard-capped at 100 matching lines so the model's context never drowns in output.147Respects <code>.gitignore</code> and <code>.khaelorignore</code>. When results are truncated,148the full result set is spilled to a file the agent can search further.</p>149150<h2 id="glob"><code>glob</code><a class="anchor" href="#glob">#</a></h2>151<p>Filesystem discovery by name pattern — <code>**/*.ts</code>,152<code>src/**/config.*</code> — returning up to 100 paths ordered newest-first. Respects153ignore files and skips built-in noise (<code>node_modules/</code>, <code>.git/</code>,154<code>dist/</code>) unless the pattern explicitly targets it.</p>155156<h2 id="bash"><code>bash</code><a class="anchor" href="#bash">#</a></h2>157<p>Runs short-lived shell commands — builds, tests, git, package scripts — and returns158interleaved stdout/stderr with the exit code and duration:</p>159<pre class="term" data-no-copy><code> <span class="t-dim">$ npm test</span>160 > proj@0.3.1 test161 > vitest run162 <span class="t-ok">✓</span> src/context/engine.test.ts (14 tests)163 <span class="t-dim">[exit code 0 · 3.2s · cwd /Users/x/dev/proj]</span></code></pre>164<ul>165 <li>Commands run in their own process group, non-interactively, from the project directory166 (or an explicit working directory) — never via hidden <code>cd</code> side effects.</li>167 <li>A failing exit code is a normal observation for the agent, not a crash — it reads the168 failure and fixes the cause.</li>169 <li>Permission evaluation happens on the parsed command <em>before</em> execution — see170 <a href="/docs/permissions.html">Permissions</a>.</li>171</ul>172173<h3 id="timeout">The timeout that never kills your command</h3>174<p>This is KHAELOR's answer to the classic agent failure of hanging forever on a dev server.175If a <code>bash</code> command is still running when its time budget expires (default 120 s,176max 300 s), it is <strong>not killed</strong> — it is adopted by the background process177manager, keeps running with its output continuously logged, and the agent immediately gets the178output so far plus a process id:</p>179<pre class="term" data-no-copy><code> Command still running after 120s — moved to background as process p4.180 Output so far:181 ...182 <span class="t-dim">Use process read p4 for new output, or process stop p4 to stop it.</span></code></pre>183<p>Nothing blocks forever; nothing is silently killed. (Pressing <kbd>Esc</kbd> yourself184<em>does</em> kill a foreground <code>bash</code> command — you asked for that — while185background processes survive.)</p>186187<h2 id="process"><code>process</code><a class="anchor" href="#process">#</a></h2>188<p>A real background process manager the agent can drive: <code>start</code>,189<code>list</code>, <code>read</code>, <code>write</code> (stdin), <code>stop</code>. It is what190lets KHAELOR start a dev server, keep editing, check the server's output, run tests, and check191the server again — the workflow blocking-shell agents simply cannot do.</p>192<pre class="term" data-no-copy><code> Started p3 (pid 41232): npm run dev193 <span class="t-dim">cwd /Users/x/dev/proj · log ~/.khaelor/process-logs/s_ab12/p3.log</span>194 First output (waited up to 2s):195 VITE v5.4.1 ready in 431 ms196 ➞ Local: http://localhost:5173/</code></pre>197<ul>198 <li><strong>Instant-failure detection</strong> — <code>start</code> waits up to 2 s for199 first output, so port-in-use and similar immediate crashes are caught inline without blocking200 healthy servers.</li>201 <li><strong>Nothing is lost</strong> — each process keeps an in-memory ring buffer <em>and</em>202 a complete log file on disk (<code>~/.khaelor/process-logs/<session>/<id>.log</code>).203 Reads return "new output since last read"; older output stays readable by offset or from the log.</li>204 <li><strong>Interactive processes</strong> — <code>write</code> sends stdin (REPLs, prompts),205 then automatically reads the response.</li>206 <li><strong>Clean stops</strong> — <code>stop</code> terminates the whole process group207 (SIGTERM, 3 s grace, SIGKILL), so grandchild processes don't linger.</li>208 <li><strong>Lifecycle</strong> — processes survive <kbd>Esc</kbd> interruptions but end with209 the session (with notice). Exits are detected and shown even if nobody is reading.</li>210</ul>211<p>You can watch and control everything yourself in <a href="/docs/commands.html#cmd-processes"><code>/processes</code></a>;212the status bar shows a live count of running processes.</p>213214<h2 id="truncation">Output truncation and spill files<a class="anchor" href="#truncation">#</a></h2>215<p>Every tool that can produce large output truncates it <strong>middle-out</strong> — head and216tail kept, one explicit marker in between — and spills the complete output to disk:</p>217<pre class="term" data-no-copy><code> [... 1,842 lines omitted (58 KB). Full output:218 ~/.khaelor/tool-output/s_ab12/bash-toolu_9.txt — read or grep that file for the rest.]</code></pre>219<p>The agent gets the spill path and can <code>read</code> or <code>grep</code> it; you see a220<code>· truncated</code> badge on the tool row and can expand from the same file. Spill221files are session-scoped, garbage-collected with the session, and capped at 512 MB222globally (oldest sessions pruned first). A 40,000-line test log can never destroy your223conversation layout — what settles into the transcript is bounded.</p>224225<h2 id="inspecting">Inspecting tool calls<a class="anchor" href="#inspecting">#</a></h2>226<ul>227 <li>Live: <kbd>Ctrl+T</kbd> toggles a rolling 12-line tail of the currently-running tool.</li>228 <li>After: <kbd>d</kbd> prints the most recent edit's diff; <code>/diff</code> opens the full229 session diff viewer; each turn's tool calls can be expanded into full detail blocks on demand.</li>230 <li>Always: every tool call — inputs, results, approval decisions — is a durable event in the231 <a href="/docs/sessions.html#event-log">session event log</a>.</li>232</ul>233234<div class="pager">235 <div><span class="label">Previous</span><a href="/docs/commands.html">← Commands & keyboard</a></div>236 <div class="next"><span class="label">Next</span><a href="/docs/permissions.html">Permissions →</a></div>237</div>238239</article>240</div></main>241242<footer class="site-footer"><div class="inner">243 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>244 <span>Anthropic-powered · terminal-native by design</span>245</div></footer>246247</body>248</html>249