How to use the codegraph agent skill: install and query code graphs

What does the codegraph skill make the agent do?

An agent skill is a folder of instructions and scripts that an AI agent loads when a task matches its description. This skill tells the agent how to use CodeScope, which indexes source code into two layers: structure (functions, calls, imports, classes, modules) and evolution (commits, file changes, function modifications). Each function also gets a semantic embedding.

With this in place the agent can answer questions such as who calls a function, which code is dead or highly coupled, or what a change might affect, instead of relying only on text search. It can also fetch GitHub issues to trace bugs to likely code locations and help score and compare open pull requests.

• Call graphs, callers and callees, and dependencies
• Dead code, hotspots, module coupling and architecture reports
• Semantic search and impact analysis
• Bug root cause analysis from GitHub issues
• Class diagrams (UML) and PR review with risk scoring, conflict detection and labeling

Install the codegraph skill

Download the ZIP of the skill from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Alternatively, in the Claude apps go to Settings → Capabilities → Skills and upload the ZIP.

The skill also needs the codegraph-ai Python package. Install it in a virtual environment so it stays isolated from your other tools.

• Requires Python with pip
• Files included: SKILL.md, bug-analysis.md, pr-analysis.md, patterns.md, schema.md, and evals/evals.json

Create or check a code index

The skill works on an indexed repository. Run the index command from the root of a git repository. The --lang auto option detects languages from file extensions. The --commits flag ingests git history, which is needed for evolution queries; without it only structural analysis is available.

To check an existing index, point the status command at its database directory. If you have a pre-built database, you can set CODESCOPE_DB_DIR to skip indexing.

• Supported languages: Python, JavaScript/TypeScript, C and Java
• Add --backfill-limit 200 to compute function-level MODIFIES edges (slower; enables change_attribution and co_change)
• Set HF_HUB_OFFLINE=1 to use HuggingFace models offline

Trigger the skill with natural requests

You do not need to name the skill. The skill applies when your request involves code structure, or when a .codegraph index exists in the workspace, or when you ask to create one. Describe what you want to know in plain language and the agent decides when to use the graph.

Good requests name the thing you care about: a function, a module, a bug report number, or a pull request.

• Who calls parse_config, and what breaks if I change it?
• Which functions in this project are dead code?
• Which modules are most tightly coupled?
• Why does this project have so many bugs? Trace issue 1234 to code.
• Generate a class diagram for the payment classes.
• Review the open pull requests and tell me which ones conflict.

Run analyses from the CLI or Python

Use the CLI for status and reports. Use the Python API when you want raw Cypher queries or custom analysis. The API provides methods such as hotspots, dead_code, circular_deps, module_coupling and impact, and always closes the connection when finished.

• Report: codegraph analyze --db $CODESCOPE_DB_DIR --output report.md
• Cypher example: find callers of a function with MATCH (caller:Function)-[:CALLS]->(f:Function {name: ...})

Safety notes: scripts and network access

This skill runs scripts and uses the network. Indexing and analysis run local Python code against your repository. Fetching GitHub issues or PRs and applying labels requires GitHub access, and the source does not state the token requirement, so check the bundled documentation before supplying one. Model downloads for sentence-transformers embeddings also use the network unless you use an offline or mirror setup.

Applying GitHub labels changes shared project state. Review analysis results before letting the agent label a live repository.

• Use HF_HUB_OFFLINE=1 once models are cached
• Use HF_ENDPOINT to point at a mirror if HuggingFace is unreachable
• Review labels before applying them to a shared repository

Tips for better results

Index once and reuse the database. Re-running indexing on every question is slow. Use git history if you ask about why something changed, since evolution queries depend on it.

Ask narrow questions first. A specific function or issue number gives the agent a clear starting point for graph queries.

• Keep the index in the project so the agent finds .codegraph automatically
• Use the Python API for chained or custom queries
• Use the PR analysis workflow to write a prioritized report to a file