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

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, 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, 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:

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) 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:

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:

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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}