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>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>FAQ & troubleshooting</h1>56<p class="lead">The short answers first, the diagnostics after.</p>5758<h2 id="key">"No Anthropic API key found"<a class="anchor" href="#key">#</a></h2>59<p>KHAELOR reads the key only from the <code>ANTHROPIC_API_KEY</code> environment variable:</p>60<pre><code>export ANTHROPIC_API_KEY=sk-ant-...</code></pre>61<p>Common gotchas:</p>62<ul>63 <li>You exported it in one shell tab but launched KHAELOR in another — add the export to64 <code>~/.zshrc</code> / <code>~/.bashrc</code> and open a new shell.</li>65 <li>You put an <code>apiKey</code> field in a config file — KHAELOR rejects that on purpose66 (keys don't belong in files that get committed). Move it to the environment.</li>67 <li>The variable is set but empty — check with <code>printenv ANTHROPIC_API_KEY | wc -c</code>68 (avoid printing the key itself).</li>69</ul>7071<h2 id="node">"node: command not found" or a version error<a class="anchor" href="#node">#</a></h2>72<p>KHAELOR requires <strong>Node.js 22 or newer</strong>. Check with <code>node --version</code>.73Install or upgrade via <a href="https://nodejs.org">nodejs.org</a>, Homebrew74(<code>brew install node</code>), or a version manager (<code>nvm install 22</code>,75<code>fnm install 22</code>). If you use a version manager, make sure the shell that runs76<code>khaelor</code> has it activated.</p>7778<h2 id="eacces">npm install fails with <code>EACCES</code><a class="anchor" href="#eacces">#</a></h2>79<p>Your global npm prefix is root-owned. Use a user-owned prefix instead of sudo:</p>80<pre><code>mkdir -p ~/.npm-global81npm config set prefix ~/.npm-global82export PATH="$HOME/.npm-global/bin:$PATH" # add to your shell profile83npm install -g https://www.khaelor.sh/khaelor.tgz</code></pre>8485<h2 id="command-not-found">Installed, but <code>khaelor: command not found</code><a class="anchor" href="#command-not-found">#</a></h2>86<p>The npm global bin directory is not on your <code>PATH</code>. Find it with87<code>npm prefix -g</code> — the binary is in <code><prefix>/bin</code>. Add that88directory to <code>PATH</code> in your shell profile and open a new shell.</p>8990<h2 id="terminals">Terminal compatibility<a class="anchor" href="#terminals">#</a></h2>91<p>KHAELOR targets the terminals people actually use: Terminal.app, iTerm2, kitty, Alacritty,92the VS Code terminal, and tmux. Capabilities are negotiated at startup and everything degrades93gracefully rather than breaking:</p>94<ul>95 <li><strong><kbd>Shift+Enter</kbd> doesn't insert a newline?</strong> Your terminal doesn't96 report modified keys (kitty keyboard protocol / modifyOtherKeys). Use <kbd>Ctrl+J</kbd> —97 it works everywhere — or end the line with <code>\</code> before <kbd>Enter</kbd>.</li>98 <li><strong>Colors look wrong or washed out?</strong> KHAELOR ladders truecolor →99 256-color → 16-color based on <code>COLORTERM</code>/terminfo. Inside tmux, make sure100 tmux itself advertises truecolor (<code>set -ga terminal-overrides ",*:Tc"</code>).</li>101 <li><strong>Light terminal background?</strong> The background is detected automatically102 (OSC 11 query, falling back to <code>COLORFGBG</code>) and the light theme variant is103 selected. Detection failing means it assumes dark.</li>104 <li><strong>Selection/copy:</strong> works natively — the conversation is real terminal105 scrollback, not a repainted canvas. Select and copy as you always do.</li>106</ul>107108<h2 id="no-color">Monochrome / NO_COLOR<a class="anchor" href="#no-color">#</a></h2>109<p><code>NO_COLOR=1</code> (and <code>TERM=dumb</code>) are honored absolutely — full110monochrome output. Everything remains legible because no state is communicated by color alone:111<code>✓</code> done, <code>▸</code> tool call, <code>●</code>/<code>○</code>112running/stopped, <code>⋯</code> queued, <code>◎</code> interrupted, and113<code>passed</code>/<code>failed</code> are spelled out as words.</p>114115<h2 id="logs">Where are the logs?<a class="anchor" href="#logs">#</a></h2>116<p>Developer logs live in <code>~/.khaelor/logs/</code> and never pollute the TUI. Run with117<code>khaelor --debug</code> for verbose logging plus performance histograms118(<code>perf.jsonl</code>). Logs never contain API keys, secret environment values, or119authorization headers — sensitive values are redacted at the logging layer. Related data120locations:</p>121<table>122 <tr><th>Path</th><th>Contents</th></tr>123 <tr><td><code>~/.khaelor/logs/</code></td><td class="wrap">Developer/debug logs</td></tr>124 <tr><td><code>~/.khaelor/sessions/</code></td><td class="wrap">Session event logs (JSONL)</td></tr>125 <tr><td><code>~/.khaelor/tool-output/</code></td><td class="wrap">Full output of truncated tool results</td></tr>126 <tr><td><code>~/.khaelor/process-logs/</code></td><td class="wrap">Complete background-process output</td></tr>127</table>128129<h2 id="screen-garbled">The screen got corrupted<a class="anchor" href="#screen-garbled">#</a></h2>130<p>If another program wrote over KHAELOR's live region (a background job printing to the tty,131an SSH disconnect banner), press <kbd>Ctrl+L</kbd> to repaint it. The conversation above is132plain scrollback and is unaffected.</p>133134<h2 id="stuck-command">"Command still running — moved to background as process pN"<a class="anchor" href="#stuck-command">#</a></h2>135<p>Not an error. A shell command outlived its foreground time budget (default 120 s), so136KHAELOR moved it — still running, output intact — to the background process manager instead of137killing it or hanging. See it in <code>/processes</code>; stop it there with <kbd>s</kbd> if it138was genuinely stuck. Details: <a href="/docs/tools.html#timeout">the bash timeout redirect</a>.</p>139140<h2 id="asks-every-time">Why does it keep asking permission for the same command?<a class="anchor" href="#asks-every-time">#</a></h2>141<ul>142 <li>You've been pressing <kbd>Enter</kbd> (allow <em>once</em>). Press <kbd>A</kbd> to143 persist a grant for this project.</li>144 <li>The command contains shell operators or substitution (<code>&&</code>,145 <code>|</code>, <code>$( )</code>) — KHAELOR deliberately refuses to create standing grants146 for commands it cannot fully parse. Ask the agent to run the steps as separate simple147 commands, or add a precise rule yourself in148 <a href="/docs/permissions.html#config"><code>.khaelor/config.json</code></a>.</li>149</ul>150151<h2 id="which-models">Which models can I use?<a class="anchor" href="#which-models">#</a></h2>152<p>Any current Anthropic model — KHAELOR is Anthropic-only in V1 and ships no hard-coded model153list. Set the id with <code>/model</code>, <code>--model</code>, or the154<a href="/docs/configuration.html#model">config file</a>. If cost shows <code>n/a</code>, add155pricing for your model or ignore it — token counts are always real.</p>156157<h2 id="data-privacy">What leaves my machine?<a class="anchor" href="#data-privacy">#</a></h2>158<p>Exactly one kind of traffic: requests to the Anthropic API with the context the agent needs159(your messages, relevant file content, tool results). There is no telemetry, no analytics160beacon, and nothing else phones home. Sessions, logs, and history all live locally under161<code>~/.khaelor/</code>.</p>162163<h2 id="uninstall">Uninstalling<a class="anchor" href="#uninstall">#</a></h2>164<pre><code>npm uninstall -g khaelor165rm -rf ~/.khaelor # optional: removes sessions, history, logs</code></pre>166167<h2 id="more-help">Still stuck?<a class="anchor" href="#more-help">#</a></h2>168<p>Run with <code>khaelor --debug</code>, reproduce the problem, and send the relevant slice of169<code>~/.khaelor/logs/</code> (they are secret-free by construction) to170<a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a> with your OS, terminal emulator,171and <code>node --version</code>.</p>172173<div class="pager">174 <div><span class="label">Previous</span><a href="/docs/sessions.html">← Sessions</a></div>175</div>176177</article>178</div></main>179180<footer class="site-footer"><div class="inner">181 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>182 <span>Anthropic-powered · terminal-native by design</span>183</div></footer>184185</body>186</html>187