Code Agent

ait codeagent

Unified wrapper for invoking AI code agents (Claude Code, Gemini CLI, Codex CLI, OpenCode) with configurable per-operation model selection.

ait codeagent list-agents                              # Show available agents
ait codeagent list-models claudecode                   # List Claude models
ait codeagent resolve task-pick                        # Show configured agent/model
ait codeagent check "claudecode/opus4_6"               # Validate an agent string
ait codeagent invoke task-pick 42                      # Pick task 42 with configured agent
ait codeagent --agent-string geminicli/gemini2_5pro invoke explain src/  # Override agent
ait codeagent --dry-run invoke task-pick 42            # Preview command without running

Agent String Format

An agent string identifies both the code agent and the model to use, in the format <agent>/<model>:

claudecode/opus4_6
geminicli/gemini2_5pro
codex/gpt5_3codex
opencode/kimi_k2_5

Naming rules:

• Agent names use lowercase letters only: claudecode, geminicli, codex, opencode
• Model names use lowercase letters, digits, and underscores: opus4_6, gemini3pro, gpt5_3codex_spark
• No dots, hyphens, or uppercase characters in agent strings

Supported Agents

Operations

Each operation maps to a different use case with its own default model:

Subcommands

list-agents

Lists all supported agents and whether their CLI binary is available in PATH.

ait codeagent list-agents

Output format:

AGENT:claudecode BINARY:claude STATUS:available
AGENT:geminicli BINARY:gemini STATUS:not-found
AGENT:codex BINARY:codex STATUS:not-found
AGENT:opencode BINARY:opencode STATUS:not-found

list-models

Lists available models for one or all agents, with verification scores.

ait codeagent list-models              # All agents
ait codeagent list-models claudecode   # Claude models only

Output format:

=== claudecode ===
MODEL:opus4_6 CLI_ID:claude-opus-4-6 NOTES:Most intelligent model VERIFIED:task-pick=80,explain=80,batch-review=0

=== geminicli ===
MODEL:gemini2_5pro CLI_ID:gemini-2.5-pro NOTES:Stable, best for complex tasks VERIFIED:task-pick=0,explain=0,batch-review=0

resolve

Returns the configured agent string for an operation after applying the full resolution chain.

ait codeagent resolve task-pick

Output:

AGENT_STRING:claudecode/opus4_6
AGENT:claudecode
MODEL:opus4_6
CLI_ID:claude-opus-4-6
BINARY:claude
MODEL_FLAG:--model

check

Validates an agent string and verifies the CLI binary is available.

ait codeagent check "claudecode/opus4_6"
# OK: claudecode/opus4_6 -> claude --model claude-opus-4-6 (binary found)

invoke

Invokes the code agent for an operation. The wrapper resolves the agent/model, builds the command, exports AITASK_AGENT_STRING for tracking, and execs the agent CLI.

ait codeagent invoke task-pick 42          # Pick task 42
ait codeagent invoke explain src/main.py   # Explain a file

Configuration

The agent/model for each operation is resolved through a 4-level chain (highest priority first):

1. --agent-string flag – CLI override for a single invocation
2. Per-user config – aitasks/metadata/codeagent_config.local.json (gitignored)
3. Per-project config – aitasks/metadata/codeagent_config.json (git-tracked)
4. Hardcoded default – claudecode/opus4_6

Project config (codeagent_config.json)

Shared across the team, checked into git. Sets the default agent/model for each operation:

{
  "defaults": {
    "task-pick": "claudecode/opus4_6",
    "explain": "claudecode/sonnet4_6",
    "batch-review": "claudecode/sonnet4_6",
    "raw": "claudecode/sonnet4_6"
  }
}

User config (codeagent_config.local.json)

Per-user overrides, gitignored. Same schema as the project config. Only include operations you want to override:

{
  "defaults": {
    "task-pick": "geminicli/gemini2_5pro"
  }
}

This user would use Gemini for task-pick but inherit the project defaults for all other operations.

Both config files can be edited directly or through the Settings TUI.

Model Configuration

Models are defined in JSON files at aitasks/metadata/models_<agent>.json. Each file contains an array of model entries:

{
  "models": [
    {
      "name": "opus4_6",
      "cli_id": "claude-opus-4-6",
      "notes": "Most intelligent model for agents and coding",
      "verified": {
        "task-pick": 80,
        "explain": 80,
        "batch-review": 0
      }
    }
  ]
}

Verification Scores

Scores indicate how well a model has been tested for each operation:

• 0 – Not verified (untested or unknown quality)
• 1-49 – Partially verified (works but with known issues)
• 50-79 – Verified (works well for most cases)
• 80-100 – Highly verified (extensively tested, recommended)

Scores are displayed in the Settings TUI Models tab and help when choosing which model to assign to an operation.

Updating Models

To add new models, update notes, or check for deprecated entries, use the /aitask-refresh-code-models skill. It researches the latest models from each provider’s documentation and updates the JSON files with user approval. Verification scores can also be edited through the Settings TUI Models tab or by editing the JSON files directly.

implemented_with Metadata

When a task is implemented, the agent string is recorded in the task’s YAML frontmatter:

implemented_with: claudecode/opus4_6

This enables tracking which agent/model performed each task’s implementation for quality analysis.

How it’s populated:

1. When ait codeagent invoke runs, it exports the AITASK_AGENT_STRING environment variable before launching the agent
2. The /aitask-pick skill reads this env var during task claim and writes it to the frontmatter
3. If the env var is not set (agent was launched directly, not through the wrapper), the skill self-detects: it identifies its own agent CLI and model, looks up the model in the config file, and constructs the agent string

TUI Integration

The code agent wrapper is integrated into both TUI applications:

• Board TUI (ait board) – When you pick a task from the board (press Enter on a task card, then select “Pick”), the board invokes ait codeagent invoke task-pick <task_num> instead of hardcoding a specific agent. This means the board respects your configured agent/model for the task-pick operation.

• Code Browser (ait codebrowser) – When you launch the explain action on a file, the code browser resolves the explain operation through the wrapper to determine which agent binary to use. It performs a pre-flight check to verify the binary is in PATH and shows a user-friendly error if not found.

• Settings TUI (ait settings) – The Code Agent tab provides a visual editor for operation-to-agent bindings. You can change which agent and model is assigned to each operation (task-pick, explain, batch-review, raw) without editing JSON files directly.

Both TUIs delegate all agent resolution to the centralized configuration – there is no TUI-specific agent config.

Related

• /aitask-refresh-code-models — Research and update model configuration files
• Settings TUI — Visual editor for code agent defaults (Agent Defaults tab) and model definitions (Models tab)
• Board TUI — How to Pick a Task — Uses the task-pick operation to launch the configured agent
• Code Browser — Uses the explain operation for launching explain sessions