safe-project-graph

Portable, read-only project graph context for coding agents.

safe-project-graph combines a provider-neutral Python wrapper around code-review-graph, one canonical Agent Skill, and a small installer for the discovery paths used by Claude Code and Codex.

The graph is advisory. Agents are instructed to read the real source files and tests before changing code or making review claims.

Why this exists

The upstream project has a broad feature set. This repository exposes a narrow surface for on-demand codebase context:

• pinned code-review-graph==2.3.7 in a managed virtual environment;
• graph data outside the target repository;
• doctor, setup, build, update, status, impact, find, and related;
• no upstream installer, hooks, MCP, server, watcher, daemon, auto-refactor, embeddings, or wiki workflow is ever invoked;
• a guard that refuses to run when .code-review-graph* artifacts already exist inside the target repository.

That list describes what this wrapper runs. It is not a claim about what setup installs: the pinned upstream package declares fastmcp, mcp, watchdog, networkx, pyyaml, and tree-sitter* as its own dependencies, so those land in the managed virtual environment either way. See SECURITY.md for the full trust boundary.

Requirements

• Git
• Python 3.10+ for the skill installer (standard library only)
• Python 3.10–3.13 available for the managed graph runtime
• macOS or Linux
• network access during the first setup only

Windows has code paths in the wrapper but no CI coverage; treat it as unverified.

If the runtime Python is not discoverable on PATH, set SAFE_PROJECT_GRAPH_PYTHON to its executable.

Install

Clone this repository, then install the same canonical skill bundle for the client and scope you need.

Claude Code project skill

python3 scripts/install_skill.py \
  --client claude-code \
  --scope project \
  --target /path/to/repo

This writes only:

/path/to/repo/.claude/skills/project-graph-context/

Codex project skill

python3 scripts/install_skill.py \
  --client codex \
  --scope project \
  --target /path/to/repo

This writes only:

/path/to/repo/.agents/skills/project-graph-context/

Both clients

python3 scripts/install_skill.py \
  --client all \
  --scope project \
  --target /path/to/repo

The two installed bundles are byte-equivalent copies of skills/project-graph-context/.

User scope

python3 scripts/install_skill.py --client claude-code --scope user
python3 scripts/install_skill.py --client codex --scope user
python3 scripts/install_skill.py --client all --scope user

User installs go to ~/.claude/skills/project-graph-context/ and/or ~/.agents/skills/project-graph-context/.

Use --dry-run to print destinations without writing. Existing skills are protected unless --force is supplied. The installer never edits CLAUDE.md, AGENTS.md, permissions, hooks, MCP configuration, or client settings.

CLI

Agents resolve the installed skill root and invoke its bundled script:

cd /path/to/installed/project-graph-context
python3 scripts/project_graph.py doctor --repo /path/to/repo
python3 scripts/project_graph.py setup
python3 scripts/project_graph.py build --repo /path/to/repo
python3 scripts/project_graph.py find SessionStore --repo /path/to/repo
python3 scripts/project_graph.py related SessionStore --repo /path/to/repo
python3 scripts/project_graph.py impact --repo /path/to/repo --base HEAD

Run setup only when doctor reports that the managed runtime is missing. After the first build, use update --base HEAD for the current diff.

find and related accept --limit (default 20, capped at 100). Both read the graph database read-only and never write to the indexed repository.

setup installs with --only-binary :all:, so no dependency may execute a source build on your machine during installation.

By default runtime and graph data live below:

~/.cache/safe-project-graph/

Set SAFE_PROJECT_GRAPH_CACHE_DIR to replace that root. No graph database is created inside the indexed repository.

Compatibility

The v0.1.0 release is exercised with:

Client	Version	Discovery path
Claude Code	2.1.185	.claude/skills/project-graph-context/
Codex CLI	0.145.0	.agents/skills/project-graph-context/

The skill itself uses only the required name and description frontmatter fields from the open Agent Skills specification.

Develop and verify

python3 -m unittest discover -s tests -v
python3 -m compileall -q scripts skills tests
ruff check .
skills-ref validate skills/project-graph-context

CI runs unit tests on Ubuntu and macOS across Python 3.10, 3.11, 3.12, and 3.13, lints, validates the skill, scans for obvious secrets/private provenance, and performs a clean-room graph smoke test that installs the runtime for real and asserts the indexed repository's worktree is untouched.

See CONTRIBUTING.md for the release checklist, including how the pinned upstream version is bumped.

Security and provenance

Read SECURITY.md before reporting a vulnerability. The wrapper installs and executes a pinned third-party package; review its upstream release notes and your network policy before setup.

This project is MIT-licensed. Upstream attribution and its MIT notice are in THIRD_PARTY_NOTICES.md.