How codebase-memory-mcp Supports 43 Different Agent Surfaces: Automatic Detection and Safe Integration

The codebase-memory-mcp installer automatically detects and configures 43 distinct AI coding agent surfaces by scanning for existing client configuration files and writing MCP hooks only when markers are present, ensuring zero-permission-expansion integration across IDEs, CLIs, and cloud copilots.

The codebase-memory-mcp repository delivers a unified code-intelligence layer that works out-of-the-box with 43 different agent surfaces, ranging from local terminals to cloud-based copilots. Its design centers on automatic detection and conditional configuration, allowing the system to support diverse environments without expanding permissions beyond what each client already allows.

The Three Categories of Agent Surface Support

The system organizes its 43 supported surfaces into three distinct categories based on how configuration is applied.

Automatically Detected Surfaces (37)

The installer scans for known configuration files to identify 37 surfaces that can be configured automatically. When the installer detects a marker file—such as ~/.claude.json, $CODEX_HOME/config.toml, or .gemini/settings.json—it writes the appropriate MCP configuration directly into the client's existing config structure. This approach applies to major agents including Claude Code, Codex CLI, and Gemini-based tools.

Conditional and Explicit Surfaces (6)

For clients requiring explicit opt-in or pre-existing config paths, the installer adds 6 additional surfaces only when required files are present. Examples include ~/.continue/config.yaml for Continue.dev and Visual Studio's ~/.mcp.json. The system respects these explicit boundaries, never creating configuration files where none existed previously.

Manual and UI-Only Surfaces

Certain agents such as Warp and JetBrains AI/ACP are counted within the 43-surface total but require manual configuration or UI-based setup rather than automated installer hooks. These surfaces still receive full durable-context support once configured.

How the Detection Mechanism Works

The support for 43 different agent surfaces relies on a four-stage mechanism implemented in the installer logic.

Detection – The install command examines the filesystem for client-specific marker files. Upon discovery, it generates a tiny .mcp.json (or client-specific equivalent) containing the MCP server address and available tool definitions.

Durable Context Creation – For each configured client, the system creates a durable-context definition that instructs the agent how to pass graph results back to the host. This includes integration points such as SessionStart, SubagentStart, and PreToolUse hooks.

Hook Safety – All hooks are fail-open and permission-safe. Hooks are only added when the client already possesses a configuration file, guaranteeing that no new permissions or experimental flags are introduced. If a client cannot consume the extra context, the hooks are simply ignored.

Tiered Sub-Agents – Every surface receives three specialized sub-agents—Scout, Verify, and Auditor—that expose progressively richer graph queries while maintaining a narrow permission envelope. This design allows lightweight CLIs to access powerful graph insights without exposing the full index.

Installation and Configuration Examples

Configure all detected agent surfaces using the CLI entry point defined in pkg/pypi/src/codebase_memory_mcp/_cli.py:

# Install the MCP binary and configure all detected agents

codebase-memory-mcp install

This command automatically detects the 37 agents with existing config files, writes the corresponding MCP hook files (e.g., ~/.claude.json, ~/.codeium/windsurf/mcp_config.json), and enables the three-tier sub-agents for each surface.

Verify that a specific client has been configured by inspecting its MCP configuration:

# Check VS Code configuration

cat ~/.config/Code/User/mcp.json

Typical output shows the server configuration and available tools:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/usr/local/bin/codebase-memory-mcp",
      "args": []
    }
  },
  "tools": ["search_graph", "trace_call_path"]
}

Execute graph queries from any configured surface using the CLI:

# Search for functions matching a pattern

codebase-memory-mcp cli search_graph '{"name_pattern":"^handle.*","label":"Function"}'

Core Implementation Files

According to the codebase-memory-mcp source code, the following files implement the multi-agent support system:

• README.md (lines 371-376) – Documents the 43 surfaces and the multi-agent support strategy in the Multi-Agent Support section.
• pkg/npm/README.md (lines 10-34) – Summarizes the "43 automatic/conditional client surfaces" and lists supported agents.
• pkg/pypi/src/codebase_memory_mcp/_cli.py – Implements the CLI entry points for the installer and agent interactions.
• internal/cbm/ – Core logic that parses client-specific config formats and generates durable-context definitions.
• Client configuration templates – Runtime-generated files such as ~/.claude.json and ~/.codeium/windsurf/mcp_config.json created by the installer.

Summary

• codebase-memory-mcp supports 43 different agent surfaces through automatic detection and conditional configuration.
• 37 surfaces are configured automatically when marker files (e.g., ~/.claude.json, .gemini/settings.json) are detected.
• 6 surfaces require conditional or explicit opt-in based on existing config paths (e.g., ~/.continue/config.yaml).
• The system uses fail-open hooks that only write to existing configuration files, ensuring no permission expansion.
• Every configured surface receives three tiered sub-agents (Scout, Verify, Auditor) providing graduated access to graph queries.
• Implementation spans the CLI module, core internal logic, and runtime-generated client-specific configuration files.

Frequently Asked Questions

How does the installer avoid permission expansion when configuring 43 different agents?

The installer only writes MCP configuration files when it detects an existing client configuration file (such as ~/.claude.json or ~/.mcp.json). This "marker file" approach guarantees that the system never creates new permissions or enables experimental flags where they did not already exist, maintaining the principle of "no-surprise" permission changes across all 43 surfaces.

What are the three sub-agents (Scout, Verify, Auditor) provided to each surface?

Each of the 43 agent surfaces receives access to three tiered sub-agents that expose progressively richer graph queries. Scout provides basic discovery capabilities, Verify offers intermediate validation queries, and Auditor delivers deep graph analysis. This tiered design ensures that even lightweight CLI tools can access powerful code intelligence without exposing the full index unnecessarily.

Which agent surfaces require manual configuration rather than automatic detection?

While 37 surfaces are detected automatically and 6 are conditional, certain agents including Warp and JetBrains AI/ACP require manual setup or UI-based configuration. These are still counted within the 43-surface total and receive full durable-context support once configured, but the installer does not automatically write their configuration files.

Where is the list of 43 supported agent surfaces documented?

The complete list and categorization of the 43 agent surfaces are documented in the Multi-Agent Support section of the main README.md (lines 371-376) and summarized in pkg/npm/README.md (lines 10-34). These sections detail the specific marker files and configuration paths used for automatic detection of each supported client.

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