Provide AST and call-graph code intelligence support for coding agents via CodeGraph.

CodeGraph Integration

Mopheus supports integration with the open-source code intelligence tool CodeGraph, providing AST (Abstract Syntax Tree) and dependency graph exploration capabilities for coding agents (development, bug fixing, refactoring, code audit).

License & Commercial Use

Project Repository: colbymchenry/codegraph
License: MIT License
Commercial Support: The MIT license fully permits commercial integration, modification, and proprietary or open-source distribution.

Why Integrate CodeGraph?

In traditional LLM-assisted coding workflows, agents often rely on repeated grep searches and full file reads. This multi-turn loop is slow and consumes significant tokens.

CodeGraph indexes the repository using Tree-sitter and SQLite into structured ASTs and call graphs:

One-Shot Flow Exploration: codegraph explore returns verbatim source code with exact line numbers, call paths, and blast radius in a single query, eliminating redundant file reads.
Precise Dependency Tracking: codegraph callers and callees trace upstream callers and downstream functions.
Impact Analysis & Test Targeting: codegraph impact evaluates modification radius before code changes, while codegraph affected identifies test files needing regression runs.

Architecture & Lifecycle Integration

The Mopheus Daemon runtime integrates CodeGraph at the repository virtualization layer:

Zero-Overhead Worktree Provisioning:
- Maintains a sidecar snapshot cache named by Commit SHA (.repos/.../<repo>.git.codegraph-cache/<sha>.db) adjacent to the bare repository.
- Provisions into <worktree>/.codegraph/codegraph.db via independent file copy (<10ms), preventing SQLite lock collisions across concurrent agent tasks.
Smart Incremental Refresh:
- When remote branches evolve with new commits, the Daemon automatically performs incremental sync (codegraph sync, ~50ms) from the nearest existing snapshot instead of running a full init.
Git Isolation Protection:
- Automatically adds .codegraph to .git/info/exclude upon worktree creation, ensuring index databases are never committed to user branches.
Automated GC & Pruning:
- Combines Git active worktree metadata and branch tips to prune expired snapshots (> 7 days TTL) and excess snapshots (LRU keeping the 5 most recent).
Fail-Open Safety:
- If codegraph is not installed or indexing fails, worktree creation and agent task execution continue uninterrupted.
Repo-Aware Dynamic Skill Injection:
- During task dispatch (agent_task.go), the server automatically checks whether the task is associated with accessible Git repositories (project-specific or workspace-level default repos).
- using-codegraph is injected only when Git repositories are present. Non-coding tasks (e.g. general chat, customer support, document writing) automatically omit this skill, keeping agent prompts and workspaces 100% clean and noise-free.

Built-in Skill & Common Commands

Mopheus ships with the built-in skill using-codegraph, supporting both CLI commands and CodeGraph MCP Server Tools (e.g. codegraph_explore). Through Repo-Aware Dynamic Injection, it is automatically provided whenever an agent claims a task associated with a Git repository, requiring no manual UI assignment. Agents can immediately use the following capabilities after checking out and entering the repository worktree directory:

Command	Purpose	Example
`codegraph explore "<query>"`	Explore architecture, flow, and symbol source	`codegraph explore "CreateComment flow"`
`codegraph callers <symbol>`	Find all upstream callers of a symbol	`codegraph callers ProvisionCodeGraph`
`codegraph callees <symbol>`	Find all downstream functions called by a symbol	`codegraph callees CreateWorktree`
`codegraph impact <symbol>`	Evaluate blast radius before modifying code	`codegraph impact Cache`
`codegraph affected [files...]`	Identify test files affected by source changes	`codegraph affected server/internal/daemon/repocache/git.go`
`codegraph sync`	Incrementally sync AST index after editing code	`codegraph sync`

Installation & Prerequisites

[!NOTE] Installation Note: The current version of Mopheus does not install codegraph by default via install.sh (inclusion in the one-click installer may be considered in future releases). To enable CodeGraph intelligence, install the codegraph CLI on the host machine or container running the Mopheus Daemon.

1. Installation Method

CodeGraph provides both standalone pre-built binaries (self-contained, no Node.js required) and a Node.js npm package:

Method 1: Official One-Line Script (Recommended, No Node.js Required)

The official installer automatically downloads the matching standalone binary for Linux / macOS from GitHub Releases:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

You can also download the pre-built tarball (e.g. codegraph-linux-x64.tar.gz, codegraph-linux-arm64.tar.gz, or codegraph-darwin-arm64.tar.gz) directly from GitHub Releases and extract it to a directory in your PATH.

Method 2: Via Node.js Package Manager (If Node.js is already installed)

If your host or container already has Node.js installed, you can install globally via npm or pnpm:

# Install globally via npm
npm install -g @colbymchenry/codegraph

# Or install globally via pnpm
pnpm add -g @colbymchenry/codegraph

2. Verification

Verify that the codegraph executable is available in your system PATH:

codegraph --version

Once installed, restart the Mopheus Daemon (or dispatch a new agent task) to automatically benefit from CodeGraph intelligence acceleration.