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/faq.html5Description: FAQ and troubleshooting — API key, Node version, terminals, NO_COLOR, logs, uninstall.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>FAQ & troubleshooting — KHAELOR</title>14<meta name="description" content="KHAELOR troubleshooting: API key not set, Node version, terminal compatibility, NO_COLOR, log locations, uninstalling.">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>FAQ & troubleshooting</h1>75<p class="lead">The short answers first, the diagnostics after.</p>7677<h2 id="key">"No Anthropic API key found"<a class="anchor" href="#key">#</a></h2>78<p>KHAELOR reads the key only from the <code>ANTHROPIC_API_KEY</code> environment variable:</p>79<pre><code>export ANTHROPIC_API_KEY=sk-ant-...</code></pre>80<p>Common gotchas:</p>81<ul>82 <li>You exported it in one shell tab but launched KHAELOR in another — add the export to83 <code>~/.zshrc</code> / <code>~/.bashrc</code> and open a new shell.</li>84 <li>You put an <code>apiKey</code> field in a config file — KHAELOR rejects that on purpose85 (keys don't belong in files that get committed). Move it to the environment.</li>86 <li>The variable is set but empty — check with <code>printenv ANTHROPIC_API_KEY | wc -c</code>87 (avoid printing the key itself).</li>88</ul>8990<h2 id="node">"node: command not found" or a version error<a class="anchor" href="#node">#</a></h2>91<p>KHAELOR requires <strong>Node.js 22 or newer</strong>. Check with <code>node --version</code>.92Install or upgrade via <a href="https://nodejs.org">nodejs.org</a>, Homebrew93(<code>brew install node</code>), or a version manager (<code>nvm install 22</code>,94<code>fnm install 22</code>). If you use a version manager, make sure the shell that runs95<code>khaelor</code> has it activated.</p>9697<h2 id="eacces">npm install fails with <code>EACCES</code><a class="anchor" href="#eacces">#</a></h2>98<p>Your global npm prefix is root-owned. Use a user-owned prefix instead of sudo:</p>99<pre><code>mkdir -p ~/.npm-global100npm config set prefix ~/.npm-global101export PATH="$HOME/.npm-global/bin:$PATH" # add to your shell profile102npm install -g https://www.khaelor.sh/khaelor.tgz</code></pre>103104<h2 id="command-not-found">Installed, but <code>khaelor: command not found</code><a class="anchor" href="#command-not-found">#</a></h2>105<p>The npm global bin directory is not on your <code>PATH</code>. Find it with106<code>npm prefix -g</code> — the binary is in <code><prefix>/bin</code>. Add that107directory to <code>PATH</code> in your shell profile and open a new shell.</p>108109<h2 id="terminals">Terminal compatibility<a class="anchor" href="#terminals">#</a></h2>110<p>KHAELOR targets the terminals people actually use: Terminal.app, iTerm2, kitty, Alacritty,111the VS Code terminal, and tmux. Capabilities are negotiated at startup and everything degrades112gracefully rather than breaking:</p>113<ul>114 <li><strong><kbd>Shift+Enter</kbd> doesn't insert a newline?</strong> Your terminal doesn't115 report modified keys (kitty keyboard protocol / modifyOtherKeys). Use <kbd>Ctrl+J</kbd> —116 it works everywhere — or end the line with <code>\</code> before <kbd>Enter</kbd>.</li>117 <li><strong>Colors look wrong or washed out?</strong> KHAELOR ladders truecolor →118 256-color → 16-color based on <code>COLORTERM</code>/terminfo. Inside tmux, make sure119 tmux itself advertises truecolor (<code>set -ga terminal-overrides ",*:Tc"</code>).</li>120 <li><strong>Light terminal background?</strong> The background is detected automatically121 (OSC 11 query, falling back to <code>COLORFGBG</code>) and the light theme variant is122 selected. Detection failing means it assumes dark.</li>123 <li><strong>Selection/copy:</strong> works natively — the conversation is real terminal124 scrollback, not a repainted canvas. Select and copy as you always do.</li>125</ul>126127<h2 id="no-color">Monochrome / NO_COLOR<a class="anchor" href="#no-color">#</a></h2>128<p><code>NO_COLOR=1</code> (and <code>TERM=dumb</code>) are honored absolutely — full129monochrome output. Everything remains legible because no state is communicated by color alone:130<code>✓</code> done, <code>▸</code> tool call, <code>●</code>/<code>○</code>131running/stopped, <code>⋯</code> queued, <code>◎</code> interrupted, and132<code>passed</code>/<code>failed</code> are spelled out as words.</p>133134<h2 id="logs">Where are the logs?<a class="anchor" href="#logs">#</a></h2>135<p>Developer logs live in <code>~/.khaelor/logs/</code> and never pollute the TUI. Run with136<code>khaelor --debug</code> for verbose logging plus performance histograms137(<code>perf.jsonl</code>). Logs never contain API keys, secret environment values, or138authorization headers — sensitive values are redacted at the logging layer. Related data139locations:</p>140<table>141 <tr><th>Path</th><th>Contents</th></tr>142 <tr><td><code>~/.khaelor/logs/</code></td><td class="wrap">Developer/debug logs</td></tr>143 <tr><td><code>~/.khaelor/sessions/</code></td><td class="wrap">Session event logs (JSONL)</td></tr>144 <tr><td><code>~/.khaelor/tool-output/</code></td><td class="wrap">Full output of truncated tool results</td></tr>145 <tr><td><code>~/.khaelor/process-logs/</code></td><td class="wrap">Complete background-process output</td></tr>146</table>147148<h2 id="screen-garbled">The screen got corrupted<a class="anchor" href="#screen-garbled">#</a></h2>149<p>If another program wrote over KHAELOR's live region (a background job printing to the tty,150an SSH disconnect banner), press <kbd>Ctrl+L</kbd> to repaint it. The conversation above is151plain scrollback and is unaffected.</p>152153<h2 id="stuck-command">"Command still running — moved to background as process pN"<a class="anchor" href="#stuck-command">#</a></h2>154<p>Not an error. A shell command outlived its foreground time budget (default 120 s), so155KHAELOR moved it — still running, output intact — to the background process manager instead of156killing it or hanging. See it in <code>/processes</code>; stop it there with <kbd>s</kbd> if it157was genuinely stuck. Details: <a href="/docs/tools.html#timeout">the bash timeout redirect</a>.</p>158159<h2 id="asks-every-time">Why does it keep asking permission for the same command?<a class="anchor" href="#asks-every-time">#</a></h2>160<ul>161 <li>You've been pressing <kbd>Enter</kbd> (allow <em>once</em>). Press <kbd>A</kbd> to162 persist a grant for this project.</li>163 <li>The command contains shell operators or substitution (<code>&&</code>,164 <code>|</code>, <code>$( )</code>) — KHAELOR deliberately refuses to create standing grants165 for commands it cannot fully parse. Ask the agent to run the steps as separate simple166 commands, or add a precise rule yourself in167 <a href="/docs/permissions.html#config"><code>.khaelor/config.json</code></a>.</li>168</ul>169170<h2 id="which-models">Which models can I use?<a class="anchor" href="#which-models">#</a></h2>171<p>Any current Anthropic model — KHAELOR is Anthropic-only in V1 and ships no hard-coded model172list. Set the id with <code>/model</code>, <code>--model</code>, or the173<a href="/docs/configuration.html#model">config file</a>. If cost shows <code>n/a</code>, add174pricing for your model or ignore it — token counts are always real.</p>175176<h2 id="data-privacy">What leaves my machine?<a class="anchor" href="#data-privacy">#</a></h2>177<p>Exactly one kind of traffic: requests to the Anthropic API with the context the agent needs178(your messages, relevant file content, tool results). There is no telemetry, no analytics179beacon, and nothing else phones home. Sessions, logs, and history all live locally under180<code>~/.khaelor/</code>.</p>181182<h2 id="uninstall">Uninstalling<a class="anchor" href="#uninstall">#</a></h2>183<pre><code>npm uninstall -g khaelor184rm -rf ~/.khaelor # optional: removes sessions, history, logs</code></pre>185186<h2 id="more-help">Still stuck?<a class="anchor" href="#more-help">#</a></h2>187<p>Run with <code>khaelor --debug</code>, reproduce the problem, and send the relevant slice of188<code>~/.khaelor/logs/</code> (they are secret-free by construction) to189<a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a> with your OS, terminal emulator,190and <code>node --version</code>.</p>191192<div class="pager">193 <div><span class="label">Previous</span><a href="/docs/sessions.html">← Sessions</a></div>194</div>195196</article>197</div></main>198199<footer class="site-footer"><div class="inner">200 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>201 <span>Anthropic-powered · terminal-native by design</span>202</div></footer>203204</body>205</html>206