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/configuration.html5Description: Configuration — file locations, precedence, all settings, model selection, thinking mode and output budget.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>Configuration — KHAELOR</title>14<meta name="description" content="KHAELOR configuration: file locations and precedence, model selection, thinking mode, output budget, and permissions.">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>Configuration</h1>56<p class="lead">Plain JSON files you can edit by hand, a <code>/config</code> panel when you'd57rather not, and a strict precedence order so there is never a mystery about which value wins.</p>5859<h2 id="files">File locations and precedence<a class="anchor" href="#files">#</a></h2>60<table>61 <tr><th>Scope</th><th>Path</th><th>Use for</th></tr>62 <tr><td>User</td><td><code>~/.khaelor/config.json</code></td><td class="wrap">Your personal defaults across all projects</td></tr>63 <tr><td>Project</td><td><code>.khaelor/config.json</code></td><td class="wrap">Per-repository settings and permission grants (commit it if the team shares them)</td></tr>64</table>65<p>Values merge with this precedence (highest first):</p>66<pre data-no-copy><code>CLI flags → project config → user config → environment → built-in defaults</code></pre>67<p>So <code>khaelor --model claude-opus-4-5</code> overrides everything for that session, a68project's <code>.khaelor/config.json</code> overrides your user file, and the environment is69consulted only for the API key.</p>7071<h2 id="settings">All settings<a class="anchor" href="#settings">#</a></h2>72<table>73 <tr><th>Key</th><th>Type</th><th>Default</th><th>Meaning</th></tr>74 <tr>75 <td><code>model</code></td><td>string</td><td><code>claude-sonnet-4-5</code></td>76 <td class="wrap">The Anthropic model id (or alias) used for agent turns. Never a hard-coded permanent list — any current Anthropic model id works.</td>77 </tr>78 <tr>79 <td><code>auxModel</code></td><td>string</td><td><code>claude-haiku-4-5</code></td>80 <td class="wrap">A cheaper Anthropic model used for auxiliary work such as context-compaction summaries.</td>81 </tr>82 <tr>83 <td><code>thinking</code></td><td>string</td><td><code>adaptive</code></td>84 <td class="wrap">Extended-thinking mode: <code>off</code>, <code>adaptive</code> (the model thinks when the task warrants it), or <code>always</code>.</td>85 </tr>86 <tr>87 <td><code>maxOutputTokens</code></td><td>integer</td><td><code>16000</code></td>88 <td class="wrap">Output token budget per model response. Also visible/cyclable in <code>/model</code> with <kbd>o</kbd>.</td>89 </tr>90 <tr>91 <td><code>permissions</code></td><td>object</td><td><code>{}</code></td>92 <td class="wrap">Permission rules — capability → <code>allow</code> / <code>ask</code> / <code>deny</code>, with optional per-subject patterns. Full syntax in <a href="/docs/permissions.html#config">Permissions</a>.</td>93 </tr>94</table>9596<p>A complete example:</p>97<pre><code>{98 "model": "claude-sonnet-4-5",99 "auxModel": "claude-haiku-4-5",100 "thinking": "adaptive",101 "maxOutputTokens": 16000,102 "permissions": {103 "file.read": "allow",104 "process.execute": {105 "npm test": "allow",106 "npm run *": "allow",107 "*": "ask"108 }109 }110}</code></pre>111<p>Unknown fields are ignored (forward compatibility). Malformed values fail loudly at load112time with the offending file and field named.</p>113114<h2 id="api-key">The API key<a class="anchor" href="#api-key">#</a></h2>115<p>The Anthropic API key comes <strong>exclusively</strong> from the environment:</p>116<pre><code>export ANTHROPIC_API_KEY=sk-ant-...</code></pre>117<p>Config files that contain an <code>apiKey</code> / <code>api_key</code> /118<code>anthropicApiKey</code> field are <strong>rejected at load time</strong> — the error names119the field but never echoes its value. This makes it structurally hard to commit a key to a120repository. The key is never displayed, never logged, and redacted from every debug view;121<code>/config</code> shows only <code>set via environment ✓</code>.</p>122123<h2 id="model">Choosing a model<a class="anchor" href="#model">#</a></h2>124<p>Three equivalent ways, highest precedence first:</p>125<ol>126 <li><strong>Per session:</strong> <code>khaelor --model <anthropic-model-id></code></li>127 <li><strong>Interactively:</strong> <a href="/docs/commands.html#cmd-model"><code>/model</code></a>128 — pick from your configured models/aliases, cycle thinking with <kbd>t</kbd> and the output129 budget with <kbd>o</kbd>; applies immediately and shows in the status bar.</li>130 <li><strong>Persistently:</strong> set <code>model</code> in the project or user config file.</li>131</ol>132<p>Because Anthropic model identifiers evolve, KHAELOR ships no permanent hard-coded model133list — the defaults are aliases you can override anywhere.</p>134135<h2 id="thinking">Thinking mode and output budget<a class="anchor" href="#thinking">#</a></h2>136<ul>137 <li><code>thinking: "off"</code> — no extended thinking; fastest and cheapest.</li>138 <li><code>thinking: "adaptive"</code> (default) — the model uses extended thinking when the139 task warrants it. While it thinks, the status line shows a compact140 <code>● Thinking · 4s</code> — thinking is never the centerpiece of the UI.</li>141 <li><code>thinking: "always"</code> — maximum deliberation on every turn.</li>142</ul>143<p><code>maxOutputTokens</code> caps each response. The context inspector144(<code>/context</code>) shows this as the "reserved output" slice of the window, so you can see145exactly what a larger budget costs you in usable context.</p>146147<h2 id="config-panel">The <code>/config</code> panel<a class="anchor" href="#config-panel">#</a></h2>148<pre class="term" data-no-copy><code> ┌─ config ── ~/.khaelor/config.json · .khaelor/config.json ─┐149 <span class="t-accent">❯</span> Model claude-sonnet-4-5150 Thinking adaptive151 Max output 16000152 Permissions 12 rules →153 Theme khaelor-dark154 API key set via environment <span class="t-ok">✓</span>155 └──────────────────────────────────────────────────────────┘156 <span class="t-dim">↑↓ navigate · Enter edit · p project scope · Esc close</span></code></pre>157<p>Edits write to a real config file — <kbd>p</kbd> toggles between user and project scope,158and the target file is always shown before writing. The files remain the source of truth; the159panel is just a convenient editor over them.</p>160161<h2 id="project-instructions">Project instructions<a class="anchor" href="#project-instructions">#</a></h2>162<p>KHAELOR automatically discovers project-level instruction files and folds them into the163agent's context: <code>KHAELOR.md</code> is the native format, with compatibility for164<code>CLAUDE.md</code> and <code>AGENTS.md</code>. Precedence flows from general to specific —165instructions closer to your working path refine global ones:</p>166<pre data-no-copy><code>~/.khaelor/KHAELOR.md → repository/KHAELOR.md → nested/directory/KHAELOR.md</code></pre>167<p>Use them for repository conventions: build commands, test invocations, style rules, "never168touch these files". The <code>/context</code> inspector shows exactly how many tokens your169instructions occupy.</p>170171<h2 id="other-files">Everything else under <code>~/.khaelor/</code><a class="anchor" href="#other-files">#</a></h2>172<table>173 <tr><th>Path</th><th>Contents</th></tr>174 <tr><td><code>~/.khaelor/config.json</code></td><td class="wrap">User configuration</td></tr>175 <tr><td><code>~/.khaelor/sessions/</code></td><td class="wrap">Persistent session event logs (JSONL)</td></tr>176 <tr><td><code>~/.khaelor/prompt-history.jsonl</code></td><td class="wrap">Composer history, per project</td></tr>177 <tr><td><code>~/.khaelor/tool-output/</code></td><td class="wrap">Spilled full tool output, session-scoped, auto-pruned</td></tr>178 <tr><td><code>~/.khaelor/process-logs/</code></td><td class="wrap">Complete background-process logs</td></tr>179 <tr><td><code>~/.khaelor/logs/</code></td><td class="wrap">Developer logs (with <code>--debug</code>); never pollute the TUI, never contain secrets</td></tr>180</table>181182<div class="pager">183 <div><span class="label">Previous</span><a href="/docs/permissions.html">← Permissions</a></div>184 <div class="next"><span class="label">Next</span><a href="/docs/sessions.html">Sessions →</a></div>185</div>186187</article>188</div></main>189190<footer class="site-footer"><div class="inner">191 <span>KHAELOR — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></span>192 <span>Anthropic-powered · terminal-native by design</span>193</div></footer>194195</body>196</html>197