<!--
KHAELOR
File: README.md
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# KHAELOR

**A terminal-native autonomous engineering agent powered by Anthropic.**

KHAELOR is not another Claude Code clone. It combines the strongest architectural ideas from Claude Code, Hermes Agent, OpenCode, OpenHands, and mini-swe-agent — with its own architecture and identity, built on one principle:

```
Understand first. Design second. Implement third.
```

## Install

```sh
npm install -g khaelor
```

Or via the hosted installer:

```sh
curl -fsSL https://www.khaelor.sh/install.sh | sh
```

## Usage

```sh
export ANTHROPIC_API_KEY=sk-ant-...
khaelor                      # start the interactive TUI in the current project
khaelor --model <model-id>   # pick an Anthropic model
khaelor --print "prompt"     # non-interactive: run one agent turn, print the answer
```

Inside the TUI:

- `/model` `/config` `/permissions` `/context` `/sessions` `/resume` `/new` `/compact` `/cost` `/status` `/diff` `/processes` `/help` `/quit`
- `Ctrl+K` — universal command palette
- `@` — fuzzy file mentions · `!cmd` — shell mode · `Esc` — interrupt immediately
- Type while the agent works — steering messages are queued and injected safely

## Architecture

A deliberately small kernel surrounded by services:

```
TUI → Session Engine → Agent Kernel → { Context Engine · Tool Runtime · Model Runtime }
                                        Repository Index · Workspace · Permissions
```

- **Event-sourced sessions** — append-only JSONL logs; resume = replay
- **First-class streaming** — typed event bus, 16 ms coalesced rendering
- **7 powerful tools** — read · write · edit (9-strategy replacer) · grep · glob · bash · process (background process manager)
- **Capability-based permissions** — allow/ask/deny with precise, persisted grants
- **Context engine** — token-pressure-aware compaction with structured checkpoints, prompt-cache byte-stability
- **Custom ANSI renderer** — print-once scrollback, bounded live region, flat memory, sub-millisecond input latency

Design documents live in `docs/` (`ARCHITECTURE.md`, `EVENT_MODEL.md`, `TUI_DESIGN.md`, `TOOL_PROTOCOL.md`, `PERMISSION_MODEL.md`); the Phase 0 reference research lives in `docs/research/`.

## Development

```sh
npm install
npm run check        # typecheck + lint + tests + mandatory header check
npm run dev          # run from source
npx tsx src/tui/demo.ts   # TUI demo with mocked model events
```

V1 is Anthropic-only by design. The model layer is isolated behind a single `ModelClient` interface — clean architecture, not a provider framework.

## Author

Simon-Pierre Boucher — contact@spboucher.ai