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

Written by aiman init and aiman switch.

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.