Configuring Aerix

Everything here is taken from the code: the keys and defaults, the flags and the interactive keys. aerix config show prints the effective settings, one line per value, each with the file it came from or default.

Settings files and precedence

Aerix reads six files, highest precedence first:

<cwd> is the directory Aerix runs in (or --cwd), not the git root: project settings, skills and agents are read from the current directory's .aerix/ and .claude/.

Claude Code files contribute only these keys: hooks, env, enabledPlugins, extraKnownMarketplaces and attribution. Every other key in them (permissions, model, statusLine, theme and the rest) is ignored, with one stderr line per distinct key: aerix: settings: ignored key "<key>" (from <file>); the live screen shows each as a note in its startup block. The same happens for an unknown top-level key in an Aerix file, including safety, which no longer exists.

Merging. Files are applied lowest first. An object merges leaf by leaf, so a project file that sets context.tool_caps.read keeps the user file's other caps, and one that sets pool.max_connections keeps the user's pool.members. hooks and env merge one level: an entry (an event name, a variable) from a higher file replaces the lower file's entry. Anything that is not an object (a number, a string, an array such as pool.members) is replaced whole. enabledPlugins and extraKnownMarketplaces may be spelled in either case form (enabled_plugins, extra_known_marketplaces).

Errors. A file that is not JSON, not an object, or has a value of the wrong type is an error naming the key and the file, and Aerix does not start. Unknown fields inside a section (a typo such as pool.member) are errors too.

Settings keys

pool

How Aerix finds or starts the pool and which members it binds.

Each pool.members entry:

Binding rules: with no members configured, a pool that holds exactly one member uses it as main. With members configured there must be one main; a member the pool does not hold is loaded when everything the pool holds is configured; a pool holding a model you did not configure is refused, naming both (stop it or configure it). A decision member that fails to load is skipped with one stderr line (the live screen shows it as a note in its startup block) and main routes.

pools

delegation

context

tui

Keys shared with Claude Code

tune

What aerix tune and aerix profile sync reflect with (see Profiles).

Others

Command line

aerix [--plain] [--resume ID | --continue] [options]   interactive mode
aerix -p PROMPT [options]                               one headless request
aerix [options] < FILE                                  the same, the prompt from stdin

Mode selection: -p is headless. Without -p, a terminal on stdin is interactive and a pipe on stdin is a headless prompt. tui.plain, TERM unset, empty or dumb, or a non-terminal on either side gives plain mode. NO_COLOR removes colour.

Subcommands:

Exit codes: 0 done; 1 failed or killed (the reason on stderr), or an error; 2 the turn budget ran out; 3 no pool (none listening and none could be started, it holds other models, or it went away during the run); 64 usage error.

Instruction files and memory

Aerix puts these files, in full, into one pinned instructions segment at the start of every context, each headed by its path. Lowest precedence first:

1. ~/.claude/CLAUDE.md
2. $XDG_CONFIG_HOME/aerix/AERIX.md
3. For each directory from the git root (or the cwd outside a repository) down to the cwd: CLAUDE.md, .claude/CLAUDE.md, AGENTS.md, AERIX.md.
4. Memory: MEMORY.md from Claude Code's project memory directory (~/.claude/projects/<cwd with every non-alphanumeric character as ->/memory/) and from Aerix's ($XDG_DATA_HOME/aerix/memory/<project key>/).

A file reached twice (an AGENTS.md symlinked to CLAUDE.md) is read once. @path imports are not expanded, and only MEMORY.md is read from a memory directory, not the files it lists. The system prompt names Aerix's memory directory so the model can write there with its tools; Aerix itself writes nothing to it.

Skills

A skill is a directory holding SKILL.md with frontmatter. Aerix looks in <cwd>/.aerix/skills/, <cwd>/.claude/skills/, ~/.claude/skills/, then each enabled plugin's skill directories and its commands/*.md files (one skill per file, named by the file). The first skill found with a name wins.

In the body, $ARGUMENTS is replaced by the arguments and, for a plugin skill, ${CLAUDE_PLUGIN_ROOT} by the plugin's root. A prompt whose first line is /name args is replaced by the skill's text before routing (capped under tool_caps.skill); the model loads a skill with the skill tool. A file over 1 MiB, or not a regular file, is refused unread.

Agent definitions

*.md files with frontmatter in <cwd>/.aerix/agents/, <cwd>/.claude/agents/, ~/.claude/agents/ and enabled plugins' agent directories; the first with a name wins. The agent tool's description lists each by name and description (cut to 120 characters).

The body is added to the implementer's context as a pinned # Agent: <name> segment.

Plugins and marketplaces

Aerix installs Claude Code plugins. A marketplace is a git repository or a local directory with .claude-plugin/marketplace.json. Plugin sources github, url, git-subdir and relative paths are supported; npm, archive and command are refused by name. MCP declarations (.mcp.json, mcpServers) are skipped with one line. Aerix's installs and clones live under $XDG_DATA_HOME/aerix/plugins/; plugins Claude Code installed (~/.claude/plugins/) are used in place. Installing does not enable: set "enabledPlugins": {"name@marketplace": true} in any settings file. A plugin contributes skills, commands (as skills), agents and hooks.

Hooks

Aerix runs Claude Code's hooks contract. Hooks come from the hooks object of every settings file above (all six; a settings handler identical to one in a lower file runs once) and from each enabled plugin's hooks/hooks.json and declared hooks. config show prints the merged hooks value, but every file's hooks run.

Events fired: SessionStart (matcher source startup or resume), UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, PreCompact (trigger auto), SessionEnd. Aerix's own events, same shape: RouteDecision, AgentSpawn, Verify, ContextCompact. Matchers see Claude Code's tool names: Read, Write, Edit, Bash, Glob, Grep, Agent, and Aerix's RepoMap, Plan, Context, Skill; inputs use Claude's field names (file_path, old_string, run_in_background, ...).

A command handler runs under sh with the event JSON on stdin; exit 0 passes, exit 2 blocks with stderr given to the model, other exits warn; decision, reason, continue, additionalContext, systemMessage and updated input or output are honoured. The default timeout is 600 s (30 s for UserPromptSubmit and SessionEnd). The environment carries CLAUDE_PROJECT_DIR and AERIX_PROJECT_DIR (the git root, else the cwd), AERIX_SESSION_ID, settings.env, and for a plugin's handlers CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA and their AERIX_ twins. transcript_path is a Claude Code format projection of the session.

Where Aerix differs from Claude Code:

• permission_mode is bypassPermissions; ask and defer let the call go ahead with a system message, and a defer's updatedInput is ignored (17). PermissionRequest hooks are reported and never run.
• Only command handlers run; http, mcp_tool, prompt and agent are noted once and skipped. An if rule of the Tool(glob) form is evaluated on tool events; other forms are skipped with a warning (18).
• A Stop or SubagentStop hook can keep an agent going at most 5 times per run (20).
• continue: false ends the agent that fired it: the root fails, a subagent is killed (25).
• Settings and their hooks come from the cwd; CLAUDE_PROJECT_DIR and the hook's working directory are the git root (26).
• async handlers run under their timeout and are ended when the run ends; their output reaches the model at the firing agent's next fire point; asyncRewake runs as async (30).
• tool_response is shaped per tool; a failed call fires PostToolUse with the error text, not PostToolUseFailure (31).
• Hooks never inherit CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA, their AERIX_ twins, CURSOR_PLUGIN_ROOT or COPILOT_CLI from Aerix's own environment (33).
• disableAllHooks is not read (34).
• Notification fires only as idle_prompt (the matcher value), once, after the interactive screen has waited 60 s on you after a request, with the message Aerix is waiting for your input; there are no permission prompts, so no other type fires. Escalation never fires: escalation is not built. SessionEnd gets 30 s, not Claude Code's 1.5 s.

Keys and slash commands (interactive mode)

From tui::HELP:

Where data lives

The project key is the first 16 hex digits of sha256 over the git remote origin (normalised to host/path), else over the absolute path; two clones of one remote share sessions and memory. $XDG_CACHE_HOME/aerix/ is not used.