AI Tool Auto-Detection for Init

Status: ✅ Complete · Priority: Medium · Created: 2025-11-26 · Tags: init, dx, ai-agents, ux

Project: lean-spec
Team: Core Development

Overview

Auto-detection of installed AI CLI tools during lean-spec init to pre-select relevant options in the AI tools prompt. Improves UX by showing users which tools were detected and why.

Detection Methods

User Experience

When running lean-spec init, users now see:

🔍 Detected AI tools:
   Claude Code / Claude Desktop (CLAUDE.md)
      └─ ~/.claude directory found
   GitHub Copilot (AGENTS.md - default)
      └─ github.copilot extension installed
      └─ github.copilot-chat extension installed

? Which AI tools do you use?
❯◉ Claude Code / Claude Desktop (CLAUDE.md)
 ◯ Gemini CLI (GEMINI.md)
 ◉ GitHub Copilot (AGENTS.md - default)

Detected tools are pre-selected, reducing manual configuration.

Design

Detection Configuration

Each AI tool in AI_TOOL_CONFIGS now has an optional detection property:

interface AIToolConfig {
  file: string;
  description: string;
  default: boolean;
  usesSymlink: boolean;
  detection?: {
    commands?: string[];     // CLI commands to check
    configDirs?: string[];   // Config directories in ~
    envVars?: string[];      // Environment variables
    extensions?: string[];   // VS Code extension IDs
  };
}

Detection Logic

1. Commands: Uses which (Unix) or where (Windows) to check PATH
2. Config Dirs: Checks for directories in $HOME
3. Env Vars: Simple process.env check
4. Extensions: Scans ~/.vscode/extensions for extension folders

Fallback Behavior

• If no tools detected → falls back to copilot only (AGENTS.md is the primary file)
• If tools detected → pre-selects detected tools
• Always ensures at least one AGENTS.md tool is selected (primary file)
• -y flag uses copilot only (no symlinks created)

Plan

• Add detection config to AIToolConfig interface
• Implement commandExists() helper
• Implement configDirExists() helper
• Implement envVarExists() helper
• Implement extensionInstalled() helper
• Create detectInstalledAITools() function
• Create getDefaultAIToolSelection() function
• Update init command to show detection results
• Update checkbox to use detected defaults

Test

• lean-spec init shows detection results when tools found
• Detected tools are pre-selected in checkbox
• Detection reasons shown for each tool
• Falls back to defaults when nothing detected
• Works on macOS (tested)
• Works on Windows (not tested)
• Works on Linux (not tested)

Notes

Supported AI Tools (Alphabetical)

Future Enhancements

• Add more detection methods (running processes, recent activity)
• Detect tool versions
• Suggest MCP configuration for detected tools