"""AI Agent Detection Module.
Detects installed AI agents (Claude Desktop, Claude Code, Auggie, Cursor,
Windsurf, Continue, Codex, Gemini CLI) by checking for their configuration
files in platform-specific directories.
Design Decision: Cross-platform path detection with environment variable support
Rationale: Different platforms store application data in different locations.
This module abstracts platform-specific logic to provide consistent detection
across macOS, Windows, and Linux.
Trade-offs:
- Simplicity: Hard-coded paths vs. registry/config scanning
- Coverage: Known agents vs. plugin architecture for extensibility
- Performance: File system checks are fast enough for this use case
Alternatives Considered:
1. Registry scanning (Windows): Rejected - adds complexity, not all agents register
2. Process scanning: Rejected - agent may not be running during install
3. Plugin architecture: Deferred - YAGNI until more agents need support
Future Extensibility: AgentConfig dataclass allows easy addition of new agents
by simply adding entries to AGENT_CONFIGS list.
"""
from __future__ import annotations
import os
import platform
from dataclasses import dataclass
from pathlib import Path
@dataclass
class AgentConfig:
"""Configuration for an AI agent detection.
Attributes:
name: Human-readable agent name (e.g., "Claude Desktop")
id: Machine-readable identifier (e.g., "claude-desktop")
config_paths: Platform-specific paths to config directory
config_file: Name of the config file to modify
config_key_path: JSON path to MCP servers configuration
"""
name: str
id: str
config_paths: dict[str, Path]
config_file: str
config_key_path: str = "mcpServers"
@dataclass
class DetectedAgent:
"""Information about a detected AI agent.
Attributes:
name: Human-readable agent name
id: Machine-readable identifier
config_path: Absolute path to the configuration file
exists: Whether the config file currently exists
"""
name: str
id: str
config_path: Path
exists: bool
# Agent configuration registry
AGENT_CONFIGS = [
AgentConfig(
name="Claude Desktop",
id="claude-desktop",
config_paths={
"darwin": Path.home() / "Library" / "Application Support" / "Claude",
"win32": (
Path(os.environ.get("APPDATA", "")) / "Claude"
if platform.system() == "Windows"
else Path()
),
"linux": Path.home() / ".config" / "Claude",
},
config_file="claude_desktop_config.json",
),
AgentConfig(
name="Claude Code",
id="claude-code",
config_paths={
"darwin": Path.home() / "Library" / "Application Support" / "Code" / "User",
"win32": (
Path(os.environ.get("APPDATA", "")) / "Code" / "User"
if platform.system() == "Windows"
else Path()
),
"linux": Path.home() / ".config" / "Code" / "User",
},
config_file="settings.json",
),
AgentConfig(
name="Auggie",
id="auggie",
config_paths={
"darwin": Path.home() / "Library" / "Application Support" / "Auggie",
"win32": (
Path(os.environ.get("APPDATA", "")) / "Auggie"
if platform.system() == "Windows"
else Path()
),
"linux": Path.home() / ".config" / "Auggie",
},
config_file="config.json",
),
AgentConfig(
name="Cursor",
id="cursor",
config_paths={
"darwin": Path.home() / ".cursor",
"win32": (
Path.home() / ".cursor" if platform.system() == "Windows" else Path()
),
"linux": Path.home() / ".cursor",
},
config_file="mcp.json",
),
AgentConfig(
name="Windsurf",
id="windsurf",
config_paths={
"darwin": Path.home() / ".codeium" / "windsurf",
"win32": (
Path.home() / ".codeium" / "windsurf"
if platform.system() == "Windows"
else Path()
),
"linux": Path.home() / ".codeium" / "windsurf",
},
config_file="mcp_config.json",
),
AgentConfig(
name="Continue",
id="continue",
config_paths={
"darwin": Path.home() / ".continue",
"win32": (
Path.home() / ".continue" if platform.system() == "Windows" else Path()
),
"linux": Path.home() / ".continue",
},
config_file="config.json",
),
AgentConfig(
name="Codex",
id="codex",
config_paths={
"darwin": Path.home() / ".codex",
"win32": (
Path.home() / ".codex" if platform.system() == "Windows" else Path()
),
"linux": Path.home() / ".codex",
},
config_file="config.toml",
),
AgentConfig(
name="Gemini CLI",
id="gemini-cli",
config_paths={
"darwin": Path.home() / ".gemini",
"win32": (
Path.home() / ".gemini" if platform.system() == "Windows" else Path()
),
"linux": Path.home() / ".gemini",
},
config_file="settings.json",
),
]
class AgentDetector:
"""Detects installed AI agents on the current system.
Performance:
- Time Complexity: O(n) where n is number of configured agents
- Space Complexity: O(n) for storing detection results
- File system checks are I/O bound, typically <10ms per agent
Usage:
detector = AgentDetector()
agents = detector.detect_all()
for agent in agents:
if agent.exists:
print(f"Found {agent.name} at {agent.config_path}")
"""
def __init__(self) -> None:
"""Initialize agent detector with current platform."""
self.platform = self._get_platform()
def _get_platform(self) -> str:
"""Get normalized platform identifier.
Returns:
Platform identifier: 'darwin', 'win32', or 'linux'
Error Handling:
Unknown platforms default to 'linux' (most compatible)
"""
system = platform.system().lower()
if system == "darwin":
return "darwin"
elif system == "windows":
return "win32"
else:
return "linux"
def detect_agent(self, agent_id: str) -> DetectedAgent | None:
"""Detect a specific AI agent by ID.
Args:
agent_id: Agent identifier (e.g., 'claude-desktop')
Returns:
DetectedAgent if found, None if agent_id is unknown
Example:
agent = detector.detect_agent("claude-desktop")
if agent and agent.exists:
print(f"Config at: {agent.config_path}")
"""
config = self._get_agent_config(agent_id)
if not config:
return None
config_dir = config.config_paths.get(self.platform)
if not config_dir:
return None
config_path = config_dir / config.config_file
exists = config_path.exists()
return DetectedAgent(
name=config.name,
id=config.id,
config_path=config_path,
exists=exists,
)
def detect_all(self) -> list[DetectedAgent]:
"""Detect all configured AI agents.
Returns:
List of DetectedAgent objects for all known agents on this platform
Example:
agents = detector.detect_all()
installed = [a for a in agents if a.exists]
print(f"Found {len(installed)} installed agents")
"""
detected = []
for config in AGENT_CONFIGS:
config_dir = config.config_paths.get(self.platform)
if not config_dir:
continue
config_path = config_dir / config.config_file
exists = config_path.exists()
detected.append(
DetectedAgent(
name=config.name,
id=config.id,
config_path=config_path,
exists=exists,
)
)
return detected
def _get_agent_config(self, agent_id: str) -> AgentConfig | None:
"""Get configuration for a specific agent.
Args:
agent_id: Agent identifier
Returns:
AgentConfig if found, None otherwise
"""
for config in AGENT_CONFIGS:
if config.id == agent_id:
return config
return None
