Cookbook

Concrete recipes — each one uses the workflow KHAELOR was built around.

Fix a bug, verified#

khaelor
❯ users report the export button 500s when the list is empty — find it and fix it

KHAELOR explores with symbols/refs/read (understand), submits a design (a small one auto-approves), edits, and the verify loop runs your typecheck and tests before it answers. If a test fails, it repairs — bounded to 3 rounds, then an honest report.

Compare two models on the same task#

❯ /replay            # type the finished session's id — re-runs its user turns
❯ /model             # or switch model first, then /replay
❯ /sdiff             # "<idA> <idB>" — turns, tool calls, files, tokens, verify failures

The replay executes inside a throwaway git worktree, so re-run tool calls never touch your working copy. Run it twice, diff the runs.

Two features in parallel#

❯ /spawn             # "fix the auth bug"
❯ /spawn             # "add rate limiting to the API"
❯ /tasks             # watch both: phase, diff stats, verify state
❯ /merge             # supervised --no-ff merge of each finished branch

Each subtask gets its own worktree, branch (khaelor/<id>), and child session with attenuated permissions. Conflicts abort cleanly; ask KHAELOR to resolve them with both designs in context.

Nightly dependency maintenance#

khaelord goal add "npm deps stay fresh without breaking changes" \
  --type maintain --schedule "0 6 * * 1" \
  --check "npm outdated --json | grep -q ." --escalation draft-pr
khaelord start

Monday 06:00: the cheap check decides whether there is anything to do; a real run opens a worktree, designs, upgrades, verifies, and leaves a branch for your review. Budget-capped, fully event-logged.

Branch an exploration without losing the thread#

❯ /fork              # pick "❯ now add tests" — the fork opens there
# try the risky approach in the fork; the original session is untouched
❯ /sessions          # jump back anytime — resume = exact replay

Teach KHAELOR your project once#

❯ our error convention: everything returns Result<T,KError>, never throw in src/core — remember that

The agent persists it via the remember tool into .khaelor/MEMORY.md with provenance. Every future session starts knowing it. Audit with /memory.

Headless in CI or scripts#

khaelor --print "summarize the churn in src/ since last tag" --gate off
# permission asks resolve to DENY headless — grant what CI needs in .khaelor/config.json

High-stakes change, strict gate#

khaelor --gate strict
❯ migrate the session store from JSON to SQLite

Nothing gets written until you approve the design panel — goal, approach, files, risks, verification — with a single keystroke.