spb/khaelor Public

1<!--2KHAELOR3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# KHAELOR910**A terminal-native autonomous engineering agent powered by Anthropic.**1112KHAELOR 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:1314```15Understand first. Design second. Implement third.16```1718## Install1920```sh21npm install -g khaelor22```2324Or via the hosted installer:2526```sh27curl -fsSL https://www.khaelor.sh/install.sh | sh28```2930## Usage3132```sh33export ANTHROPIC_API_KEY=sk-ant-...34khaelor                      # start the interactive TUI in the current project35khaelor --model <model-id>   # pick an Anthropic model36khaelor --print "prompt"     # non-interactive: run one agent turn, print the answer37```3839Inside the TUI:4041- `/model` `/config` `/permissions` `/context` `/sessions` `/resume` `/new` `/compact` `/cost` `/status` `/diff` `/processes` `/help` `/quit`42- `Ctrl+K` — universal command palette43- `@` — fuzzy file mentions · `!cmd` — shell mode · `Esc` — interrupt immediately44- Type while the agent works — steering messages are queued and injected safely4546## Architecture4748A deliberately small kernel surrounded by services:4950```51TUI → Session Engine → Agent Kernel → { Context Engine · Tool Runtime · Model Runtime }52                                        Repository Index · Workspace · Permissions53```5455- **Event-sourced sessions** — append-only JSONL logs; resume = replay56- **First-class streaming** — typed event bus, 16 ms coalesced rendering57- **7 powerful tools** — read · write · edit (9-strategy replacer) · grep · glob · bash · process (background process manager)58- **Capability-based permissions** — allow/ask/deny with precise, persisted grants59- **Context engine** — token-pressure-aware compaction with structured checkpoints, prompt-cache byte-stability60- **Custom ANSI renderer** — print-once scrollback, bounded live region, flat memory, sub-millisecond input latency6162Design 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/`.6364## Development6566```sh67npm install68npm run check        # typecheck + lint + tests + mandatory header check69npm run dev          # run from source70npx tsx src/tui/demo.ts   # TUI demo with mocked model events71```7273V1 is Anthropic-only by design. The model layer is isolated behind a single `ModelClient` interface — clean architecture, not a provider framework.7475## Author7677Simon-Pierre Boucher — contact@spboucher.ai78