# How AI Agents Are Validated During Initialization in Spec-Kit: CLI vs IDE

> Discover how Spec-Kit validates AI agents during initialization. Learn the differences between CLI agent checks and IDE agent validation skipping using the requires cli flag.

- Repository: [GitHub/spec-kit](https://github.com/github/spec-kit)
- Tags: deep-dive
- Published: 2026-03-05

---

**Spec-Kit validates CLI-based AI agents by checking for executable presence via `check_tool()`, while IDE-based agents skip validation entirely based on the `requires_cli` flag in `AGENT_CONFIG`.**

The `specify init` command in the [github/spec-kit](https://github.com/github/spec-kit) repository performs distinct validation paths depending on whether an AI agent requires a command-line tool or operates purely within an IDE. This differentiation ensures that CLI-dependent agents like Claude or Gemini are actually installed before initialization proceeds, whereas IDE-integrated agents like GitHub Copilot or Cursor are assumed to be managed by their host environments.

## Agent Configuration Metadata Drives Validation

All supported agents are defined in the `AGENT_CONFIG` dictionary located in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) (lines 26-62). Each entry specifies metadata including a critical boolean flag named `requires_cli` that determines the validation strategy.

```python
"claude": {
    "name": "Claude Code",
    "folder": ".claude/",
    "commands_subdir": "commands",
    "install_url": "https://docs.anthropic.com/.../setup",
    "requires_cli": True,            # ← triggers executable check

},
"copilot": {
    "name": "GitHub Copilot",
    "folder": ".github/",
    "commands_subdir": "agents",
    "install_url": None,
    "requires_cli": False,           # ← skips CLI validation

},

```

The `requires_cli` field serves as the single source of truth for how spec-kit validates AI agents during initialization. When set to `True`, the system verifies the binary exists in `PATH`; when `False`, no tool presence check occurs.

## Validation Logic in the Init Command

Inside the `init` command implementation (lines 99-107 of [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py)), the code branches based on the `requires_cli` flag:

```python
if not ignore_agent_tools:
    agent_config = AGENT_CONFIG.get(selected_ai)
    if agent_config and agent_config["requires_cli"]:
        install_url = agent_config["install_url"]
        if not check_tool(selected_ai):
            # Show an error panel with install_url and abort

```

**CLI-based agents** (`requires_cli == True`) trigger the `check_tool()` function. If the tool is missing, spec-kit displays an error panel (lines 103-109) containing the `install_url` and aborts the initialization.

**IDE-based agents** (`requires_cli == False`) bypass this block entirely. Since these agents function within the IDE itself rather than as standalone executables, spec-kit assumes availability through the editor's extension system.

## How `check_tool` Validates CLI Executables

The `check_tool` function (defined at lines 544-566 in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py)) performs executable discovery using `shutil.which()` with special handling for specific agents:

```python
def check_tool(tool: str, tracker: StepTracker = None) -> bool:
    if tool == "claude":
        # Special handling for the Claude CLI alias

        if CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():
            return True
    if tool == "kiro-cli":
        found = shutil.which("kiro-cli") is not None or shutil.which("kiro") is not None
    else:
        found = shutil.which(tool) is not None
    # ... UI tracking updates ...

    return found

```

Key implementation details include:
- **Standard lookup**: Uses `shutil.which(tool)` for most binaries like `gemini` or `qwen`
- **Claude exception**: Checks for a local wrapper at `CLAUDE_LOCAL_PATH` before falling back to PATH
- **Kiro flexibility**: Accepts either `kiro-cli` or `kiro` as valid executable names
- **Progress reporting**: Optionally accepts a `StepTracker` to update the UI with "available" or "not found" status

## Bypassing Validation with `--ignore-agent-tools`

Users can skip validation entirely using the `--ignore-agent-tools` flag. When provided, this sets the `ignore_agent_tools` boolean to `True`, short-circuiting the validation block before any `check_tool()` calls occur. This is particularly useful in CI/CD pipelines where the agent tool might be installed later or in separate containers.

## Practical Initialization Examples

### CLI-Based Agent (Claude)

When initializing with a CLI-dependent agent, spec-kit verifies the executable exists:

```bash
$ specify init myproj --ai claude

# If `claude` is not in PATH:

# → error panel:

#   claude not found

#   Install from: https://docs.anthropic.com/en/docs/claude-code/setup

```

### IDE-Based Agent (Copilot)

IDE-based agents proceed immediately without tool checks:

```bash
$ specify init myproj --ai copilot

# No tool check happens; project is created immediately.

```

### Skipping Validation in Automation

For environments where the tool is not yet installed:

```bash
$ specify init myproj --ai claude --ignore-agent-tools

```

## Summary

- **CLI-based agents** (Claude, Gemini, Qwen, Opencode) set `requires_cli: True` in `AGENT_CONFIG`, triggering `check_tool()` to verify executable presence in `PATH`
- **IDE-based agents** (Copilot, Cursor, Windsurf) set `requires_cli: False`, skipping validation entirely as the IDE manages the agent
- **Special cases** in `check_tool()` handle Claude's local wrapper path and Kiro's dual executable names (`kiro-cli` or `kiro`)
- **Override option** `--ignore-agent-tools` bypasses all validation for automation scenarios
- **Error handling** for missing CLI tools displays the configured `install_url` before aborting initialization

## Frequently Asked Questions

### What happens if a CLI-based AI agent is not installed?

Spec-kit calls `check_tool()` during `specify init` and, if the executable is missing, displays an error panel containing the agent's `install_url` (as configured in `AGENT_CONFIG`) and aborts the initialization process unless `--ignore-agent-tools` is specified.

### Why don't IDE-based agents require validation?

IDE-based agents like GitHub Copilot or Cursor operate as extensions within the IDE itself rather than standalone command-line tools. Since spec-kit cannot verify IDE extension installation from the CLI, these agents set `requires_cli: False` in their configuration, causing the validation block to be skipped entirely.

### How does spec-kit handle different executable names for the same agent?

The `check_tool` function in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py) contains agent-specific logic. For example, the Kiro agent checks for both `kiro-cli` and `kiro` using `shutil.which()` on both names, while Claude checks for a local wrapper file at `CLAUDE_LOCAL_PATH` before searching PATH.

### Can I initialize a project for an AI agent that I haven't installed yet?

Yes. By passing the `--ignore-agent-tools` flag to `specify init`, you bypass the `check_tool()` validation entirely. This allows project setup to complete even when CLI tools are missing, which is useful for setting up projects in containers or CI environments where tools are installed separately.