CodeGraph

The CodeGraph A/B benchmark compares agent performance (using Claude Opus) with the codegraph MCP server versus without it (using only built-in Read/Grep/Glob/Bash tools).

Key Performance Metrics

• File Reads: CodeGraph reduces total file reads by approximately 76% (e.g., 159 $\rightarrow$ 38 reads).
• Tool Calls: Reduces tool calls by ~41% (e.g., 321 $\rightarrow$ 189 calls).
• Wall-clock Time: Mean duration decreases from 48s to 38s.
• Efficiency: CodeGraph prevents 'agent thrashing' in large repositories where agents typically fall back to expensive shell find/grep (Bash) calls or spawn sub-agents.

When to use CodeGraph

• Medium/Large Repositories: Significant wins are seen in backends with complex flows (e.g., route $\rightarrow$ handler $\rightarrow$ service). CodeGraph avoids the need for many greps/globs and shell commands.
• Small Repositories: In very small repos (a few files), the performance may tie with or be slightly slower than the 'without' arm due to MCP and indexing overhead.

The telemetry-worker is the first-party endpoint for telemetry.getcodegraph.com. It receives anonymous usage telemetry from CodeGraph clients.

Key behaviors:

• Validation: Validates incoming batches against a strict allowlist. Unknown events are dropped and unknown properties are stripped.
• Privacy: Never reads or stores client IP addresses.
• Rate Limiting: Limits requests per machine_id.
• Storage: Writes surviving events to a Cloudflare D1 database (env.DB) using ctx.waitUntil to ensure writes happen off the response path.
• Fail-silent: If a D1 write fails, it is logged to Workers Logs, but the client still receives a 204 response to prioritize availability over data completeness.
• Data Lifecycle: A nightly cron job rolls up raw events into anonymous daily counts and purges raw rows older than the RETENTION_DAYS (default 90) to stay within D1 storage limits.

CodeGraph extracts references to constants and properties using the following logic:

• Class Constants: UserModel::class or Foo::CONST extracts the class name at the receiver's position if the name matches the capitalized regex ^[A-Z][A-Za-z0-9_]*$.
• Relative Constants: self::CONST or static::X does NOT emit a reference.
• Scoped Properties: UserModel::$conn extracts UserModel.
• Qualified Constants: \App\Models\User::class does NOT emit a reference.
• Lowercase Receivers: References using lowercase receivers (e.g., $x->y) are not accepted as valid class/constant access patterns for extraction.

These extractions are only performed when the access occurs within a function or method body.

// Extracts 'UserModel'
UserModel::class;

// Extracts 'UserModel'
UserModel::$conn;

// Does NOT extract (relative scope)
self::CONST;

// Does NOT extract (qualified name)
\App\Models\User::class;

CodeGraph uses a proportional allocation model (allocateExploreBudget) to decide how many bytes (source code) are sent to an AI agent. Instead of a flat cap per file, it reserves a share of the total 'envelope' (the maximum output character limit) for each file based on its relevance and importance.

The Allocation Logic:

1. Weight Calculation: Weight = score × worth × (spine ? 2 : 1).
   • score: The relevance score.
   • worth: A secondary penalty applied to the rank to ensure that high-ranking but low-value files (like generated boilerplate) don't consume the entire budget.
   • spine: A multiplier for files on the primary code path.
2. Relative Cliff: Files with a weight less than 15% of the top weight (capped at SCORE_FLOOR_MAX) receive zero source code. They only receive metadata (path, symbols, and line numbers). This saves space and prevents low-value files from consuming maxFiles slots.
3. Floor and Split: Every admitted file is guaranteed a minimum of MIN_CHARS (700 characters) to ensure at least one complete method is visible. The remaining budget is then split proportionally based on weight.
4. Safety Valve: No single file can exceed 70% of the total envelope.

This model ensures that 'diffuse' queries (asking about many components) get a spread of files, while 'precise' queries concentrate bytes on the most relevant files.

CodeGraph uses ExploreSessionState to track what has already been sent to an agent during an MCP session. This prevents redundant data transfer by allowing the system to recognize when a file or specific line ranges have already been delivered.

Key Data Recorded

For each resolved project root in a session, the following is tracked:

• callCount / responseBytes: Cumulative totals for the session.
• calls[]: Detailed history of recent calls, including:
  • The query used.
  • Emitted line ranges (spans).
  • A content fingerprint (hash) for the source bytes.
  • The 1-based session index.

Constraints and Behavior

• Per Session, Not Persisted: State is lost when a new agent session starts.
• Per Resolved Project Root: State is keyed by the actual project path, not the path typed by the agent.
• Bounded Memory: To prevent unbounded growth, state is limited by EXPLORE_SESSION_LIMITS (e.g., 8 retained calls per project).
• Daemon-Safe: State is stored on the MCPSession object, not on shared handlers or workers, ensuring different agents do not share history.