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

> Discover how codebase-memory-mcp automatically detects and integrates 43 agent surfaces with zero permission expansion across IDEs, CLIs, and cloud copilots.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: deep-dive
- Published: 2026-07-15

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/pkg/pypi/src/codebase_memory_mcp/_cli.py):

```bash

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

```bash

# Check VS Code configuration

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

```

Typical output shows the server configuration and available tools:

```json
{
  "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:

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) (lines 371-376) and summarized in [`pkg/npm/README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.