Aigon uses a unified aigon config command with two scopes:

• Project (.aigon/config.json) — per-project settings
• Global (~/.aigon/config.json) — user-wide settings

Project scope is the default. Use --global for user-wide settings.

Config commands

# Initialise
aigon config init                           # Create project config (auto-detects profile)
aigon config init --global                  # Create global config
 
# Set values (dot-notation for nested keys)
aigon config set profile web
aigon config set --global terminalApp warp
aigon config set iterate.validationCommand "npm run test:iterate"
aigon config set fleet.testInstructions "run the repo's fast validation command"
 
# Get values (shows where the value comes from)
aigon config get terminal
aigon config get profile
 
# Show merged effective config
aigon config show
aigon config show --global
aigon config show --project
 
# View model configuration
aigon config models

Global config

Created with aigon config init --global at ~/.aigon/config.json:

{
  "terminal": "warp",
  "tmuxApp": "terminal",
  "agents": {
    "cc": { "cli": "claude", "implementFlag": "--permission-mode acceptEdits" },
    "gg": { "cli": "gemini", "implementFlag": "--yolo" },
    "cx": { "cli": "codex", "implementFlag": "" },
    "mv": { "cli": "vibe", "implementFlag": "-p" }
  }
}

Project config

Created with aigon config init at .aigon/config.json:

{
  "profile": "web",
  "appId": "my-app",
  "devProxy": {
    "command": "npm run dev",
    "healthCheck": "/api/health",
    "basePort": 3000
  }
}

Configuration options

Iterate validation override

If the profile-aware default is too broad for your repo, set an explicit iterate gate in .aigon/config.json:

{
  "iterate": {
    "validationCommand": "npm run test:iterate"
  }
}

Use this to point feature iteration at your fast, scoped validation command. Keep full-suite checks for the close or pre-push gate.

Per-worktree setup (worktreeSetup)

Worktrees are fresh checkouts — they do not share node_modules, virtualenvs, or any other build artefacts with your main repo. If your agents need those to exist before they start, set worktreeSetup in .aigon/config.json:

{
  "worktreeSetup": "npm ci"
}

When it runs: after git worktree add and .env.local is written, before the agent launches. One execution per worktree.

Where to set it: .aigon/config.json (project scope). Aigon does not detect or guess your stack — you tell it what to do.

Examples:

{ "worktreeSetup": "npm ci" }

{ "worktreeSetup": "ln -s ../../node_modules node_modules" }

The symlink form is faster (under a second) when your project’s tooling tolerates a linked node_modules. The install form is safer when it doesn’t.

Failure semantics: the command runs with a 120-second timeout. If it fails or times out, Aigon warns and continues — the agent launches anyway and can retry.

Anti-pattern: Aigon does not detect or guess your stack. There is no built-in pnpm/yarn/bun/pip/cargo fallback. If you need per-worktree setup, declare it explicitly via worktreeSetup.

Precedence

Priority order: Environment variable > Project config > Global config > Defaults

Use aigon config get <key> to see which level a value comes from. Set AIGON_TERMINAL=code to override the terminal for a single session.

Project profiles

Aigon auto-detects your project type and adapts behaviour accordingly:

aigon profile detect        # See what Aigon auto-detects
aigon profile show          # View current profile and settings
aigon profile set ios       # Override auto-detection
aigon apply                 # Regenerate templates after changing profile

Profile behaviour

• web / api: Dev server enabled, agent-specific ports assigned, .env.local created in worktrees
• ios / android / library / generic: No dev server, no PORT, project-appropriate test instructions

Port configuration (web/api profiles)

PORT=3400 in .env → cc=3401, gg=3402, cx=3403, cu=3404, mv=3405

Ports are derived from your base PORT using fixed offsets, avoiding clashes when running multiple projects.

Model selection

Per-agent, per-task model selection:

# View resolved models
aigon config models
 
# Override for specific agent/task
aigon config set agents.cc.models.research haiku
aigon config set agents.gg.models.evaluate gemini-2.5-flash
 
# Per-session override via env var (highest priority)
AIGON_CC_RESEARCH_MODEL=haiku aigon config models

Env var pattern: AIGON_{AGENT}_{TASK}_MODEL where AGENT is CC/GG/CX/CU and TASK is RESEARCH/IMPLEMENT/EVALUATE.

Spec complexity: Feature and research specs can declare a complexity level in YAML frontmatter. When you start work from the dashboard, that label pre-selects model and effort via each agent’s complexity ladder, then your config defaults. Global keys above apply when you pick Default in the picker or when complexity is missing. See Agents → Spec complexity and model defaults.

CLI flag overrides

Default “yolo mode” flags auto-approve agent commands:

For stricter permissions:

aigon config set --global agents.cc.implementFlag ""

Set implementFlag to "" (empty string) to require manual approval prompts.

Hooks

Hooks let you run custom scripts before and after Aigon commands. Define hooks in docs/aigon-hooks.md:

## pre-feature-start
 
\`\`\`bash
if [ "$AIGON_MODE" = "fleet" ]; then
  for agent in $AIGON_AGENTS; do
    neon branches create --name "feature-${AIGON_FEATURE_ID}-${agent}"
  done
fi
\`\`\`

Hook behaviour

• Pre-hooks run before the command. Failure aborts the command.
• Post-hooks run after. Failure warns but doesn’t roll back.

Environment variables in hooks

aigon hooks list            # Inspect discovered hooks