Configuration — Kaeonix docs

Config layers

Kaeonix reads three layers, each overriding the one before, with the environment on top. The split matters mostly for one reason: what is safe to commit.

LAYER	SCOPE	COMMIT IT?
User	You, on this machine. Credentials and personal defaults.	No — outside the repo entirely.
Project	Everyone working in this repo. Shared rules and conventions.	Yes.
Project local	You, in this repo. Personal overrides.	No — gitignore it.

File locations

PATHS

~/.kaeonix/settings.json # user settings

~/.kaeonix/auth.json # account token, written by `kaeonix login`

~/.kaeonix/CLAUDE.md # user memory

~/.kaeonix/skills/ # your skills

~/.kaeonix/sessions/ # session history

~/.kaeonix/plugins/ # installed plugins

.kaeonix/settings.json # project settings (commit)

.kaeonix/settings.local.json # personal overrides (gitignore)

.kaeonix/skills/ # project skills (commit)

.kaeonix/mcp.json # project MCP servers (commit)

CLAUDE.md # project memory (commit)

CLAUDE.local.md # personal project memory (gitignore)

Settings

Permission rules are the highest-value thing to configure, since they apply regardless of which mode a teammate happens to be in:

.kaeonix/settings.json

{

"model": "avatar-1",

"permissions": {

"allow": ["bash(npm test)", "bash(npm run lint)"],

"deny": ["bash(terraform *)", "bash(kubectl *)"]

}

A committed project settings file also matters for headless runs, which cannot prompt. Whatever the repo declares is what an unattended agent is allowed to do.

Environment variables

Anything in settings can also be supplied from the environment under the KAEONIX_ prefix, which is what CI should use — a runner has no home directory worth persisting and no way to answer a prompt.

VARIABLE	EFFECT
`KAEONIX_API_KEY`	Authenticate without the browser flow.
`KAEONIX_MODEL`	Model for every session in this environment.
`KAEONIX_CONFIG_DIR`	Move the user layer off `~/.kaeonix/` — useful for ephemeral runners.
`KAEONIX_NO_COLOR`	Disable colour output, same as `--no-color`.

Project memory

CLAUDE.md at the repository root is loaded into the system prompt on every turn. It is the right place for conventions the agent cannot infer from the code — commit-message format, which package manager to use, directories to leave alone.

Generate a starting point by scanning the repo:

INIT

kaeonix init

AGENTS.md is read as well, so a repo already set up for other agent tooling works without duplication. Keep it short — it is prepended to every request, and a long memory file is a tax on every turn.