npx graphkeeper-cli build
npx graphkeeper-cli query co-change src/git.ts

Files that historically change alongside "src/git.ts":

     1  src/store.ts
     1  src/types.ts
     1  test/git.test.ts
     1  test/store.test.ts
     1  test/test-helpers.ts

(Real output from running GraphKeeper against its own repo, this early in its history. Co-change counts grow as a codebase accumulates more commits.)

No server, no account, no embeddings API. Every byte of output comes from git log on the repo you already have checked out.

Install

GraphKeeper ships two independent, equally first-class packages. Pick whichever fits your toolchain, or install both. Both mine the same git log co-change signal and share one on-disk .graphkeeper/graph.json schema, so a store built by either can be read back by the other.

# npm -- JavaScript/TypeScript CLI + library
npm install -g graphkeeper-cli
# or run it once with no install
npx graphkeeper-cli build

# PyPI -- Python CLI + library (genuine port, not a wrapper around the Node binary)
pip install graphkeeper-cli

The npm package requires Node.js 18 or later; the Python package requires Python 3.9 or later. Both require git on your PATH. The Python package's CLI entry point is also graphkeeper (e.g. graphkeeper build). See python/README.md for the Python-specific walkthrough, and CHANGELOG.md for each distribution's version history.

Quickstart

Run it against any git repo, including this one:

git clone https://github.com/RudrenduPaul/GraphKeeper.git
cd GraphKeeper
graphkeeper build

GraphKeeper build complete: /path/to/GraphKeeper

Co-change graph: 4 commit(s) analyzed, 80 file pair(s) found
graphify enrichment: skipped -- graphify was not found on PATH. Install it with
`uv tool install graphifyy` (or `pipx install graphifyy`) for symbol/call-graph
enrichment; GraphKeeper works fine without it, in co-change-only mode.

Wrote /path/to/GraphKeeper/.graphkeeper/graph.json

Now query it:

graphkeeper query co-change src/git.ts

Files that historically change alongside "src/git.ts":

     1  src/store.ts
     1  src/types.ts
     1  test/git.test.ts
     1  test/store.test.ts
     1  test/test-helpers.ts

If graphify is installed (uv tool install graphifyy), graphkeeper build automatically shells out to its local, no-API-key graphify extract --code-only and merges its symbol/call-graph into the same store, unlocking call-graph queries:

graphkeeper query calls mineCoChange

mineCoChange() (src/git.ts)

Calls (2):
  --> assertIsGitRepo()
  --> runGit()

Called by (1):
  <-- build()

(Also real output, from running graphkeeper build against this repo with graphify installed.)

Without graphify installed, that same command explains exactly why the answer isn't available instead of crashing or returning an empty result:

Call-graph query for "mineCoChange" is not available.

graphify was not found on PATH. Install it with `uv tool install graphifyy`
(or `pipx install graphifyy`) for symbol/call-graph enrichment; GraphKeeper
works fine without it, in co-change-only mode.

Every command also supports --json for scripts and agents:

graphkeeper query co-change src/git.ts --json

{
  "file": "src/git.ts",
  "results": [
    { "file": "src/store.ts", "count": 1 },
    { "file": "src/types.ts", "count": 1 },
    { "file": "test/git.test.ts", "count": 1 },
    { "file": "test/store.test.ts", "count": 1 },
    { "file": "test/test-helpers.ts", "count": 1 }
  ]
}

Features

• Mines real commit history, not a static snapshot. graphkeeper build runs git log --no-merges --name-only across the full history of the repo and counts every file pair that changed together in the same commit. There's no guessing at coupling from folder structure or import statements alone; the answer comes from how the codebase actually got edited over time.
• --max-files-per-commit protects the signal. A single vendoring commit or mass reformat that touches 400 files would otherwise pollute every pair in that commit. The default cap (100 files) skips commits above that threshold so real coupling doesn't drown in noise.
• Optional call-graph enrichment, never required. When graphify is on PATH, graphkeeper build shells out to its local graphify extract --code-only --no-cluster and merges the resulting symbol/call edges into the same store, unlocking graphkeeper query calls. Without graphify, GraphKeeper still works in co-change-only mode and says so plainly instead of failing.
• Every command has a --json mode. graphkeeper query co-change <file> --json and the equivalents return machine-readable output, so an agent's calling code parses a real data structure instead of scraping text.
• Two from-scratch implementations, one schema. The npm package (src/, TypeScript) and the PyPI package (python/src/graphkeeper/, Python) are independent ports, not a wrapper of one around the other. Both read and write the same .graphkeeper/graph.json, so a store built with one CLI is queryable from the other.
• Every subprocess call uses an argv array, never a shell string. Git and graphify are both invoked through spawnSync/subprocess.run with a list of arguments, so a crafted commit message or filename in the repo being analyzed can't be interpreted as shell syntax.

CLI Reference

Usage: graphkeeper [options] [command]

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  build [options] [path]  Mine git history for co-change and (if available)
                          merge in graphify's symbol/call graph
  query                   Query the GraphKeeper store built by
                          `graphkeeper build`
  help [command]          display help for command

graphkeeper build [path]

Walks path (default: current directory), runs git log --no-merges --name-only across the whole history, and counts how often each pair of files was touched in the same commit. Writes the result to .graphkeeper/graph.json.

If graphify is detected on PATH, build also runs graphify extract <path> --code-only --no-cluster (graphify's own headless, local, no-API-key AST extraction path) into a directory inside .graphkeeper/, and merges its nodes/edges into the same store. The build output always states plainly whether that enrichment was included, and why it was skipped if not.

graphkeeper query co-change <file>

Lists files that historically changed alongside <file>, ranked by how many commits touched both.

Exit code 0 when results are found, 1 when there's no co-change data for that file yet, 2 on a usage or filesystem error.

graphkeeper query calls <symbol>

Shows callers and callees of <symbol>, using graphify's calls edges from the most recent build. Only meaningful when that build included graphify enrichment; if it didn't, this prints a clear explanation of why instead of a crash or a silent empty result.

Exit code 0 when the symbol is found, 1 when it isn't (or enrichment wasn't available), 2 on a usage or filesystem error.

MCP Server

Read the full README on GitHub →