Quickstart

1 · Install

One static binary, no runtime to install alongside it. Pick your platform:

Install covers every other route — direct binary downloads for air-gapped machines, upgrading, and uninstalling.

2 · Sign in

Authentication runs through your Feyncode account. The browser flow writes a token to ~/.kaeonix/auth.json; on a headless box pass an API key instead.

To run against a model provider of your own instead, see Authentication.

3 · Your first session

Run the agent from the root of a repository. It indexes the tree, then waits for a task.

Describe what you want in plain language rather than naming files and functions — the agent searches the repository itself. Avatar starts in plan mode: it reads, maps the change, and hands back numbered steps before touching a file. Approve with , or redirect it having spent a few thousand tokens.

4 · Approving work

Once a plan is approved, Kaeonix runs in ask permission mode: read-only tools run freely, and anything that mutates your filesystem or shells out asks first. Each prompt offers allow once, allow for the session, or deny.

Cycle modes mid-session with Shift+Tab — ask, accept-edits, bypass, auto. Most people settle on accept-edits for routine work and drop back to ask when the agent is somewhere unfamiliar.

5 · Undoing it

Every write is snapshotted before it happens, so a bad edit is not a git problem. Inside a session, /undo reverts the last change and /fork branches the conversation so you can try a different approach without losing the current one.

To keep the agent away from your working tree entirely, run it in an isolated git worktree on its own branch:

Common flags

Where to next