# How the spec-kit `check` Command Verifies AI Tool Installations with the `requires_cli` Flag

> Learn how the spec-kit check command verifies AI tool installations using the requires_cli flag. See how it efficiently tests CLI tools while skipping IDE based agents.

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

---

**The `check` command iterates through the `AGENT_CONFIG` dictionary and conditionally executes the `check_tool` helper only for agents where `requires_cli` is `True`, while marking IDE-based agents as skipped and tracking all outcomes via a `StepTracker` instance.**

The `spec-kit` CLI provides a `check` command to audit your development environment for compatible AI coding assistants. This verification system relies on a configuration-driven approach where each agent declares whether it requires a local CLI installation through the `requires_cli` boolean flag. According to the spec-kit source code in [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py), the command distinguishes between CLI-dependent tools like Claude Code and IDE-integrated agents like Windsurf using this configuration flag.

## The `requires_cli` Configuration in `AGENT_CONFIG`

At lines 27–61 of [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py), the `AGENT_CONFIG` dictionary defines every supported AI assistant and its installation requirements. Each entry contains a boolean `requires_cli` field that determines the verification strategy:

- **`True`** – The agent requires a locally installed command-line binary (e.g., **Claude Code**).
- **`False`** – The agent is IDE-based and does not expose a standalone CLI (e.g., **Windsurf**).

The `check` command imports this configuration to drive its verification loop, ensuring it only searches for executables when the flag indicates a CLI dependency exists.

## Conditional Verification Logic in the `check` Command

The main verification loop resides at lines 45–53 of the `check` command implementation. For every entry in `AGENT_CONFIG` (excluding the generic placeholder), the command evaluates the `requires_cli` flag:

```python
for agent_key, agent_cfg in AGENT_CONFIG.items():
    if agent_key == "generic":
        continue
    requires_cli = agent_cfg["requires_cli"]
    tracker.add(agent_key, agent_cfg["name"])
    if requires_cli:
        # CLI-required agents: perform executable lookup

        agent_results[agent_key] = check_tool(agent_key, tracker=tracker)
    else:
        # IDE-based agents: skip CLI verification

        tracker.skip(agent_key, "IDE-based, no CLI check")
        agent_results[agent_key] = False

```

As implemented in `github/spec-kit`, this branching logic ensures that IDE-based agents do not trigger false-negative warnings for missing binaries while CLI-dependent agents undergo rigorous existence checks.

## How `check_tool` Detects Executable Installations

The `check_tool` function (lines 44–78 of [`src/specify_cli/__init__.py`](https://github.com/github/spec-kit/blob/main/src/specify_cli/__init__.py)) performs the actual filesystem and PATH lookups. It accepts a `tool` name string and an optional `StepTracker` instance, returning a boolean indicating whether the executable is available.

### Claude Code: Local Binary Special Case

For the `"claude"` tool, the function first checks a hardcoded migration path at `~/.claude/local/claude` before falling back to PATH resolution. As shown at lines 54–64, if this local file exists, the function immediately returns `True` and marks the step complete:

```python
if tool == "claude" and CLAUDE_LOCAL_PATH.is_file():
    tracker?.complete(tool, "available")
    return True

```

This handles Claude's unique installer behavior that places the binary outside standard PATH directories during certain migration scenarios.

### KiRo CLI: Legacy Name Compatibility

At lines 65–69, the function implements backward compatibility for the KiRo agent. The tool key `"kiro-cli"` resolves successfully if either `"kiro-cli"` (current name) **or** `"kiro"` (legacy name) exists in the system PATH:

```python
if tool == "kiro-cli":
    found = shutil.which("kiro-cli") or shutil.which("kiro")

```

This dual-name check prevents false negatives when users have older KiRo installations.

### Default PATH Resolution with `shutil.which`

For all other tools (lines 70–71), the function uses Python's standard library to verify executability:

```python
found = shutil.which(tool)

```

The `shutil.which()` call returns the absolute path if the executable exists in the current PATH, or `None` if the tool is not installed.

## Step Tracking and Result Reporting

The `StepTracker` instance records granular outcomes for each verification attempt:

- **`tracker.complete()`** – Marks the step as *done* when `check_tool` locates the executable.
- **`tracker.error()`** – Marks the step as *error* when the tool is not found in PATH or special locations.
- **`tracker.skip()`** – Marks the step as *skipped* for IDE-based agents where `requires_cli` is `False`.

These tracked states feed into the final summary output, ensuring users see accurate installation status without confusion over IDE agents that legitimately lack CLI binaries.

## Additional System Checks

Beyond the AI agent loop, the `check` command performs auxiliary verifications at lines 35–60 for essential development tools. It invokes the same `check_tool` helper to confirm the presence of:

- `git` – Version control system
- `code` – Visual Studio Code stable build
- `code‑insiders` – Visual Studio Code insiders build

These checks follow the identical PATH-based resolution logic but are executed outside the `AGENT_CONFIG` iteration, providing a comprehensive environment audit regardless of which AI assistants are configured.

## Summary

- The `requires_cli` flag in `AGENT_CONFIG` (lines 27–61) determines whether the `check` command searches for a local binary or skips verification.
- **CLI-required agents** trigger `check_tool()` execution (lines 45–53), which uses `shutil.which()` for standard lookups.
- **Claude Code** receives special handling for the `~/.claude/local/claude` migration path (lines 54–64).
- **KiRo** supports dual-name resolution for `"kiro-cli"` or legacy `"kiro"` (lines 65–69).
- **IDE-based agents** (like Windsurf) with `requires_cli=False` are marked as skipped via `tracker.skip()` and do not count as "found" in the final report.
- The `StepTracker` records outcomes as complete, error, or skipped for transparent reporting.

## Frequently Asked Questions

### What happens if an AI tool is installed but not in my PATH?

The `check` command primarily relies on `shutil.which()` to locate executables. If a tool is installed outside standard PATH directories, it will be reported as not found unless it matches a special case like Claude Code's local binary at `~/.claude/local/claude`. You must ensure CLI tools are accessible in your shell PATH for the `check` command to detect them.

### Why does the `check` command skip verification for some agents like Windsurf?

When `requires_cli` is set to `False` in `AGENT_CONFIG` (as it is for Windsurf at lines 27–61), the command intentionally skips CLI verification because these are IDE-based agents that do not expose standalone command-line binaries. The `tracker.skip()` method records this state to prevent false-negative warnings while acknowledging the agent is IDE-integrated.

### How does spec-kit handle renamed or legacy CLI binaries?

The `check_tool` function includes specific handlers for tools with historical name changes. For KiRo, it checks for both `"kiro-cli"` (current) and `"kiro"` (legacy) using a logical OR operation (lines 65–69). This ensures backward compatibility without requiring users to create symlinks or aliases.

### Can I verify my installation of git and VS Code using the same command?

Yes. According to the source code at lines 35–60 of the `check` command, the tool automatically verifies `git`, `code`, and `code‑insiders` installations using the same `check_tool` helper. These checks run independently of the AI agent configuration loop, providing a complete audit of your development environment in a single execution.