FAQ & troubleshooting

The short answers first, the diagnostics after.

"No Anthropic API key found"#

KHAELOR reads the key only from the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Common gotchas:

• You exported it in one shell tab but launched KHAELOR in another — add the export to ~/.zshrc / ~/.bashrc and open a new shell.
• You put an apiKey field in a config file — KHAELOR rejects that on purpose (keys don't belong in files that get committed). Move it to the environment.
• The variable is set but empty — check with printenv ANTHROPIC_API_KEY | wc -c (avoid printing the key itself).

"node: command not found" or a version error#

KHAELOR requires Node.js 22 or newer. Check with node --version. Install or upgrade via nodejs.org, Homebrew (brew install node), or a version manager (nvm install 22, fnm install 22). If you use a version manager, make sure the shell that runs khaelor has it activated.

npm install fails with EACCES#

Your global npm prefix is root-owned. Use a user-owned prefix instead of sudo:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # add to your shell profile
npm install -g https://www.khaelor.sh/khaelor.tgz

Installed, but khaelor: command not found#

The npm global bin directory is not on your PATH. Find it with npm prefix -g — the binary is in <prefix>/bin. Add that directory to PATH in your shell profile and open a new shell.

Terminal compatibility#

KHAELOR targets the terminals people actually use: Terminal.app, iTerm2, kitty, Alacritty, the VS Code terminal, and tmux. Capabilities are negotiated at startup and everything degrades gracefully rather than breaking:

• Shift+Enter doesn't insert a newline? Your terminal doesn't report modified keys (kitty keyboard protocol / modifyOtherKeys). Use Ctrl+J — it works everywhere — or end the line with \ before Enter.
• Colors look wrong or washed out? KHAELOR ladders truecolor → 256-color → 16-color based on COLORTERM/terminfo. Inside tmux, make sure tmux itself advertises truecolor (set -ga terminal-overrides ",*:Tc").
• Light terminal background? The background is detected automatically (OSC 11 query, falling back to COLORFGBG) and the light theme variant is selected. Detection failing means it assumes dark.
• Selection/copy: works natively — the conversation is real terminal scrollback, not a repainted canvas. Select and copy as you always do.

Monochrome / NO_COLOR#

NO_COLOR=1 (and TERM=dumb) are honored absolutely — full monochrome output. Everything remains legible because no state is communicated by color alone: ✓ done, ▸ tool call, ●/○ running/stopped, ⋯ queued, ◎ interrupted, and passed/failed are spelled out as words.

Where are the logs?#

Developer logs live in ~/.khaelor/logs/ and never pollute the TUI. Run with khaelor --debug for verbose logging plus performance histograms (perf.jsonl). Logs never contain API keys, secret environment values, or authorization headers — sensitive values are redacted at the logging layer. Related data locations:

The screen got corrupted#

If another program wrote over KHAELOR's live region (a background job printing to the tty, an SSH disconnect banner), press Ctrl+L to repaint it. The conversation above is plain scrollback and is unaffected.

"Command still running — moved to background as process pN"#

Not an error. A shell command outlived its foreground time budget (default 120 s), so KHAELOR moved it — still running, output intact — to the background process manager instead of killing it or hanging. See it in /processes; stop it there with s if it was genuinely stuck. Details: the bash timeout redirect.

Why does it keep asking permission for the same command?#

• You've been pressing Enter (allow once). Press A to persist a grant for this project.
• The command contains shell operators or substitution (&&, |, $( )) — KHAELOR deliberately refuses to create standing grants for commands it cannot fully parse. Ask the agent to run the steps as separate simple commands, or add a precise rule yourself in .khaelor/config.json.

Which models can I use?#

Any current Anthropic model — KHAELOR is Anthropic-only in V1 and ships no hard-coded model list. Set the id with /model, --model, or the config file. If cost shows n/a, add pricing for your model or ignore it — token counts are always real.

What leaves my machine?#

Exactly one kind of traffic: requests to the Anthropic API with the context the agent needs (your messages, relevant file content, tool results). There is no telemetry, no analytics beacon, and nothing else phones home. Sessions, logs, and history all live locally under ~/.khaelor/.

Uninstalling#

npm uninstall -g khaelor
rm -rf ~/.khaelor        # optional: removes sessions, history, logs

Still stuck?#

Run with khaelor --debug, reproduce the problem, and send the relevant slice of ~/.khaelor/logs/ (they are secret-free by construction) to contact@spboucher.ai with your OS, terminal emulator, and node --version.