The Agent Configuration System provides a centralized metadata registry for all supported AI coding assistants in Spec Kit. The AGENT_CONFIG dictionary serves as the single source of truth that drives agent discovery, validation, template generation, and project initialization behavior. This page documents the configuration structure, metadata fields, design principles, and how the configuration is consumed throughout the CLI and release pipeline.
For information about the specific agents that are supported and their characteristics, see Supported AI Agents. For details on how agent-specific context files are updated during development, see Agent Context Management. For the broader multi-agent architecture including command formats and directory conventions, see Multi-Agent Architecture.
The AGENT_CONFIG dictionary is defined in src/specify_cli/__init__.py126-229 and serves as the authoritative metadata registry for all supported AI agents. This single data structure eliminates scattered configuration and enables consistent agent handling across initialization, validation, template generation, and release packaging.
Sources: src/specify_cli/__init__.py126-229 AGENTS.md56-87
Each agent entry in AGENT_CONFIG contains four metadata fields that control how Specify interacts with that agent:
| Field | Type | Purpose | Example Values |
|---|---|---|---|
name | str | Human-readable display name shown in selection UI and help text | "Claude Code", "GitHub Copilot" |
folder | str | Directory path where agent-specific files are stored, relative to project root | ".claude/", ".github/", ".windsurf/" |
install_url | str | None | URL to installation documentation; None for IDE-based agents with no CLI tool | "https://docs.anthropic.com/...", None |
requires_cli | bool | Whether the agent requires CLI tool verification during specify init | True for CLI agents, False for IDE-based |
Sources: src/specify_cli/__init__.py126-229 AGENTS.md81-86
Agents are categorized based on their requires_cli field, which determines validation and invocation behavior:
Agents with requires_cli: True require a command-line tool to be installed and available in the system PATH:
CLI Agent Examples:
claude: Checks for claude executable (src/specify_cli/__init__.py133-138)gemini: Checks for gemini executable (src/specify_cli/__init__.py139-144)cursor-agent: Checks for cursor-agent executable (src/specify_cli/__init__.py145-150)qwen: Checks for qwen executable (src/specify_cli/__init__.py151-156)Sources: src/specify_cli/__init__.py133-222 AGENTS.md305-318
Agents with requires_cli: False are integrated into IDEs and do not require CLI tool validation:
IDE Agent Examples:
copilot: No CLI check, uses .github/agents/ (src/specify_cli/__init__.py127-132)windsurf: No CLI check, uses .windsurf/ (src/specify_cli/__init__.py169-174)kilocode: No CLI check, uses .kilocode/ (src/specify_cli/__init__.py175-180)Sources: src/specify_cli/__init__.py127-228 AGENTS.md320-326
Critical Design Decision: Dictionary keys must match the actual executable name installed on the system, not convenient shorthand.
Rationale:
check_tool() uses shutil.which(tool) to search PATH (src/specify_cli/__init__.py484-513)Example from codebase:
Sources: src/specify_cli/__init__.py145-513 AGENTS.md210-257
All agent metadata is centralized in AGENT_CONFIG to prevent scattered configuration:
Benefits:
AGENT_CONFIGfor key, config in AGENT_CONFIG.items()Sources: src/specify_cli/__init__.py126-229 AGENTS.md56-72
Each agent entry contains only the four essential metadata fields—no more, no less:
| Required Field | Cannot Be | Reason |
|---|---|---|
name | Empty string | Display name for UI |
folder | Missing or None | Directory structure required |
install_url | Removed | Can be None for IDE agents |
requires_cli | Omitted | Must explicitly state CLI requirement |
Sources: src/specify_cli/__init__.py126-229 AGENTS.md81-86
Code References:
ai_choices = {key: config["name"] for key, config in AGENT_CONFIG.items()}Sources: src/specify_cli/__init__.py981-1112
The check() command iterates over AGENT_CONFIG to validate all agent tools:
This pattern demonstrates:
requires_cli fieldagent_key directly with check_tool() (no mapping needed)Sources: src/specify_cli/__init__.py1292-1305
The release pipeline reads AGENT_CONFIG keys to generate agent-specific packages:
Note: The release script uses a manually maintained ALL_AGENTS array rather than parsing AGENT_CONFIG directly. This is a known limitation—the script is Bash-based and cannot directly read Python dictionaries.
Synchronization Requirement: When adding a new agent to AGENT_CONFIG, the ALL_AGENTS array in the release script must be manually updated to match.
Sources: AGENTS.md109-127
The table below shows which AGENT_CONFIG fields are consumed by each system component:
| Component | name | folder | install_url | requires_cli | Key |
|---|---|---|---|---|---|
| init() command | ✓ Selection UI | ✗ | ✓ Error messages | ✓ Tool checking | ✓ Validation |
| check() command | ✓ Display | ✗ | ✗ | ✓ CLI check logic | ✓ Tool checking |
| select_with_arrows() | ✓ Menu options | ✗ | ✗ | ✗ | ✓ Selection |
| check_tool() | ✗ | ✗ | ✗ | ✗ | ✓ PATH search |
| Release pipeline | ✗ | Mapped from key | ✗ | ✗ | ✓ Package naming |
| Agent context scripts | ✗ | ✓ File paths | ✗ | ✗ | ✓ Case matching |
Legend:
Sources: src/specify_cli/__init__.py350-1321
The following table lists all 17 agents currently registered in AGENT_CONFIG:
| Key | Name | Folder | Install URL | CLI Required |
|---|---|---|---|---|
copilot | GitHub Copilot | .github/ | None | ✗ |
claude | Claude Code | .claude/ | docs.anthropic.com | ✓ |
gemini | Gemini CLI | .gemini/ | github.com/google-gemini | ✓ |
cursor-agent | Cursor | .cursor/ | None | ✗ |
qwen | Qwen Code | .qwen/ | github.com/QwenLM | ✓ |
opencode | opencode | .opencode/ | opencode.ai | ✓ |
codex | Codex CLI | .codex/ | github.com/openai | ✓ |
windsurf | Windsurf | .windsurf/ | None | ✗ |
kilocode | Kilo Code | .kilocode/ | None | ✗ |
auggie | Auggie CLI | .augment/ | docs.augmentcode.com | ✓ |
codebuddy | CodeBuddy | .codebuddy/ | codebuddy.ai | ✓ |
qoder | Qoder CLI | .qoder/ | qoder.com | ✓ |
roo | Roo Code | .roo/ | None | ✗ |
q | Amazon Q Developer CLI | .amazonq/ | aws.amazon.com | ✓ |
amp | Amp | .agents/ | ampcode.com | ✓ |
shai | SHAI | .shai/ | github.com/ovh/shai | ✓ |
bob | IBM Bob | .bob/ | None | ✗ |
Statistics:
Sources: src/specify_cli/__init__.py126-229 AGENTS.md30-50
To add a new agent to AGENT_CONFIG, follow these steps:
requires_cli based on whether tool checking is neededNone for IDE-based agents, otherwise provide docs URL--ai parameter documentationALL_AGENTS array in package generation scriptCritical Validation Checklist:
folder path ends with /requires_cli correctly reflects CLI vs IDE natureinstall_url is None for IDE agentsSources: AGENTS.md54-95 src/specify_cli/__init__.py126-229
The AGENT_CONFIG dictionary is not validated at runtime, but the following invariants should be maintained:
| Invariant | Enforcement | Impact if Violated |
|---|---|---|
| Keys match executables | Documentation | check_tool() fails to find CLI tools |
| All 4 fields present | Python interpreter | KeyError when accessing missing field |
folder is non-empty string | None | Directory creation fails silently |
requires_cli is boolean | None | Conditional logic may break |
install_url is string or None | None | Type errors in error messages |
Recommended Enhancement: Add runtime validation during CLI startup to catch configuration errors early.
Sources: src/specify_cli/__init__.py126-1112
Refresh this wiki