Config Reference

AIM uses three levels of configuration:

• global user config;
• shared inventory repository config;
• machine-local config.

Global config

Path:

~/.config/aim/config.yaml

Purpose:

• store the path to the active inventory repository;
• allow aiman status, aiman sync, and aiman push to run from any directory;
• in the future, store user preferences such as editor.

Example:

repo: /home/alex/aim-loadout
loadout: documentation-work

Written by aiman init and aiman switch.

loadout (in the global config)

The name of the active pin — the loadout that aiman sync applies instead of the full inventory. A pin is persisted state: it is not reset between CLI runs and survives inventory updates until explicitly cleared.

An empty or missing field means "no pin is set" — aiman sync works as before, applying the full inventory additively. The literal string "Default" is never written as this field's value: returning to the full inventory is expressed by clearing the field, not by a special name, so the absence of a pin and Default mode are indistinguishable at the config level — this is a deliberate design choice.

The field is written by these commands:

• aiman apply --loadout <name> --pin — writes the loadout name;
• aiman apply --default and aiman apply --unpin — clear the field;
• aiman switch — unconditionally clears the field when switching repositories, even if the new repository has a loadout with the same name.

AIM does not check that the loadout exists when the pin is written — only each time it's used (aiman sync, and also a repeated aiman apply --loadout <name> --pin). This means a pin can become invalid after being saved: the loadout may have been renamed, deleted, or published from another machine. In that case, sync stops with the error pinned loadout "X" not found in inventory — see the Errors Reference.

For the pin as a concept, see Concepts; for commands and output, see the CLI Reference.

aim.yaml

Path:

<inventory>/aim.yaml

Stored in Git and identical across all machines.

Example created by aiman init:

skill_paths: {}

skill_paths is reserved for future customization of skill installation paths. In the current version, adapters use default paths and any overrides from aim.local.yaml.

Use aim.yaml only for settings that should be shared across all users of this inventory repository.

aim.local.yaml

Path:

<inventory>/aim.local.yaml

Not stored in Git. Created separately on each machine.

Example:

repo: git@github.com:you/aim-loadout.git
synced_hash: abc1234
published_hash: abc1234

adapters:
  claude_code:
    base_dir: /home/alex/.claude
  cursor:
    base_dir: /home/alex/.cursor
  codex:
    base_dir: /home/alex/.codex

mcp_env:
  context7.UPSTASH_REDIS_REST_URL: https://example.upstash.io

repo (in aim.local.yaml)

The URL of the inventory Git repository connected on this machine. Written automatically by aiman init. Do not edit manually.

adapters

Overrides the path to an AI environment's configuration directory on the current machine. Use only when the AI environment is installed in a non-standard path.

If the section is not set, AIM determines paths automatically: Claude Code — ~/.claude, Cursor — ~/.cursor, Codex CLI — ~/.codex. On Linux ~ expands to /home/<user>, on macOS to /Users/<user>, on Windows to C:\Users\<user>.

Adapter keys: claude_code, cursor, codex. Each accepts a base_dir field.

mcp_env

Stores local env variable values for MCP servers. Keys follow the format <server-name>.<VAR_NAME>.

These values may be secrets. The aim.local.yaml file must be in .gitignore.

published_hash and synced_hash

published_hash — the last commit successfully published from this machine via aiman push.

synced_hash — the last commit fully applied to AI environments via aiman sync.

These hash markers help explain the inventory state, but do not replace Git state as the source of truth for safety checks.