Skip to content
Archon

AI Assistants

You must configure at least one AI assistant. Both can be configured if desired.

Claude Code

Section titled “Claude Code”

Recommended for Claude Pro/Max subscribers.

Authentication Options

Section titled “Authentication Options”

Claude Code supports three authentication modes via CLAUDE_USE_GLOBAL_AUTH:

  1. Global Auth (set to true): Uses credentials from claude /login
  2. Explicit Tokens (set to false): Uses tokens from env vars below
  3. Auto-Detect (not set): Uses tokens if present in env, otherwise global auth
Section titled “Option 1: Global Auth (Recommended)”
CLAUDE_USE_GLOBAL_AUTH=true

Option 2: OAuth Token

Section titled “Option 2: OAuth Token”
Terminal window
# Install Claude Code CLI first: https://docs.claude.com/claude-code/installation
claude setup-token


# Copy the token starting with sk-ant-oat01-...
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-xxxxx

Option 3: API Key (Pay-per-use)

Section titled “Option 3: API Key (Pay-per-use)”
  1. Visit console.anthropic.com/settings/keys
  2. Create a new key (starts with sk-ant-)
CLAUDE_API_KEY=sk-ant-xxxxx

Claude Configuration Options

Section titled “Claude Configuration Options”

You can configure Claude’s behavior in .archon/config.yaml:

assistants:
  claude:
    model: sonnet  # or 'opus', 'haiku', 'claude-*', 'inherit'
    settingSources:
      - project      # Default: only project-level CLAUDE.md
      - user         # Optional: also load ~/.claude/CLAUDE.md

The settingSources option controls which CLAUDE.md files the Claude Code SDK loads. By default, only the project-level CLAUDE.md is loaded. Add user to also load your personal ~/.claude/CLAUDE.md.

Set as Default (Optional)

Section titled “Set as Default (Optional)”

If you want Claude to be the default AI assistant for new conversations without codebase context, set this environment variable:

DEFAULT_AI_ASSISTANT=claude

Codex

Section titled “Codex”

Authenticate with Codex CLI

Section titled “Authenticate with Codex CLI”
Terminal window
# Install Codex CLI first: https://docs.codex.com/installation
codex login


# Follow browser authentication flow

Extract Credentials from Auth File

Section titled “Extract Credentials from Auth File”

On Linux/Mac:

Terminal window
cat ~/.codex/auth.json

On Windows:

Terminal window
type %USERPROFILE%\.codex\auth.json

Set Environment Variables

Section titled “Set Environment Variables”

Set all four environment variables in your .env:

CODEX_ID_TOKEN=eyJhbGc...
CODEX_ACCESS_TOKEN=eyJhbGc...
CODEX_REFRESH_TOKEN=rt_...
CODEX_ACCOUNT_ID=6a6a7ba6-...

Codex Configuration Options

Section titled “Codex Configuration Options”

You can configure Codex’s behavior in .archon/config.yaml:

assistants:
  codex:
    model: gpt-5.3-codex
    modelReasoningEffort: medium  # 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    webSearchMode: live           # 'disabled' | 'cached' | 'live'
    additionalDirectories:
      - /absolute/path/to/other/repo

Set as Default (Optional)

Section titled “Set as Default (Optional)”

If you want Codex to be the default AI assistant for new conversations without codebase context, set this environment variable:

DEFAULT_AI_ASSISTANT=codex

How Assistant Selection Works

Section titled “How Assistant Selection Works”
  • Assistant type is set per codebase via the assistant field in .archon/config.yaml or the DEFAULT_AI_ASSISTANT env var
  • Once a conversation starts, the assistant type is locked for that conversation
  • DEFAULT_AI_ASSISTANT (optional) is used only for new conversations without codebase context
  • Workflows can override the assistant on a per-node basis with provider and model fields
  • Configuration priority: workflow-level options > config file defaults > SDK defaults