{
  "markdown": "<div align=\"center\">\n\n# GraphKeeper\n\n<!-- mcp-name: io.github.RudrenduPaul/graphkeeper -->\n<!-- Ownership-proof string for registry.modelcontextprotocol.io publishing. Do not remove. -->\n\n[![npm version](https://img.shields.io/npm/v/graphkeeper-cli.svg)](https://www.npmjs.com/package/graphkeeper-cli)\n[![PyPI version](https://img.shields.io/pypi/v/graphkeeper-cli.svg)](https://pypi.org/project/graphkeeper-cli/)\n[![npm downloads](https://img.shields.io/npm/dm/graphkeeper-cli.svg)](https://www.npmjs.com/package/graphkeeper-cli)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](./LICENSE)\n\n[Install](#install) • [Quickstart](#quickstart) • [CLI Reference](#cli-reference) • [Comparison](#comparison) • [FAQ](#faq)\n\nA local-only CLI that mines your `git log` for which files actually change\ntogether, then hands an AI coding agent a queryable answer instead of a\ngrep across the whole history.\n\n![Installing graphkeeper-cli, cloning GraphKeeper, and running graphkeeper build followed by graphkeeper query co-change against its own repo](./docs/demo.gif)\n\n</div>\n\n```bash\nnpx graphkeeper-cli build\nnpx graphkeeper-cli query co-change src/git.ts\n```\n\n```\nFiles that historically change alongside \"src/git.ts\":\n\n     1  src/store.ts\n     1  src/types.ts\n     1  test/git.test.ts\n     1  test/store.test.ts\n     1  test/test-helpers.ts\n```\n\n(Real output from running GraphKeeper against its own repo, this early in its\nhistory. Co-change counts grow as a codebase accumulates more commits.)\n\nNo server, no account, no embeddings API. Every byte of output comes from\n`git log` on the repo you already have checked out.\n\n## Install\n\nGraphKeeper ships two independent, equally first-class packages. Pick\nwhichever fits your toolchain, or install both. Both mine the same `git\nlog` co-change signal and share one on-disk `.graphkeeper/graph.json`\nschema, so a store built by either can be read back by the other.\n\n```bash\n# npm -- JavaScript/TypeScript CLI + library\nnpm install -g graphkeeper-cli\n# or run it once with no install\nnpx graphkeeper-cli build\n\n# PyPI -- Python CLI + library (genuine port, not a wrapper around the Node binary)\npip install graphkeeper-cli\n```\n\nThe npm package requires Node.js 18 or later; the Python package requires\nPython 3.9 or later. Both require `git` on your `PATH`. The Python\npackage's CLI entry point is also `graphkeeper` (e.g. `graphkeeper build`).\nSee [`python/README.md`](./python/README.md) for the Python-specific\nwalkthrough, and [CHANGELOG.md](./CHANGELOG.md) for each distribution's\nversion history.\n\n## Quickstart\n\nRun it against any git repo, including this one:\n\n```bash\ngit clone https://github.com/RudrenduPaul/GraphKeeper.git\ncd GraphKeeper\ngraphkeeper build\n```\n\n```\nGraphKeeper build complete: /path/to/GraphKeeper\n\nCo-change graph: 4 commit(s) analyzed, 80 file pair(s) found\ngraphify enrichment: skipped -- graphify was not found on PATH. Install it with\n`uv tool install graphifyy` (or `pipx install graphifyy`) for symbol/call-graph\nenrichment; GraphKeeper works fine without it, in co-change-only mode.\n\nWrote /path/to/GraphKeeper/.graphkeeper/graph.json\n```\n\nNow query it:\n\n```bash\ngraphkeeper query co-change src/git.ts\n```\n\n```\nFiles that historically change alongside \"src/git.ts\":\n\n     1  src/store.ts\n     1  src/types.ts\n     1  test/git.test.ts\n     1  test/store.test.ts\n     1  test/test-helpers.ts\n```\n\nIf [graphify](https://github.com/Graphify-Labs/graphify) is installed\n(`uv tool install graphifyy`), `graphkeeper build` automatically shells out to\nits local, no-API-key `graphify extract --code-only` and merges its\nsymbol/call-graph into the same store, unlocking call-graph queries:\n\n```bash\ngraphkeeper query calls mineCoChange\n```\n\n```\nmineCoChange() (src/git.ts)\n\nCalls (2):\n  --> assertIsGitRepo()\n  --> runGit()\n\nCalled by (1):\n  <-- build()\n```\n\n(Also real output, from running `graphkeeper build` against this repo with\ngraphify installed.)\n\n![Running graphkeeper build with graphify installed, merging its symbol/call-graph into the same store, then graphkeeper query calls answering a call-graph question from the enriched store](./docs/graphify-enrichment.gif)\n\nWithout graphify installed, that same command explains exactly why the\nanswer isn't available instead of crashing or returning an empty result:\n\n```\nCall-graph query for \"mineCoChange\" is not available.\n\ngraphify was not found on PATH. Install it with `uv tool install graphifyy`\n(or `pipx install graphifyy`) for symbol/call-graph enrichment; GraphKeeper\nworks fine without it, in co-change-only mode.\n```\n\nEvery command also supports `--json` for scripts and agents:\n\n```bash\ngraphkeeper query co-change src/git.ts --json\n```\n\n```json\n{\n  \"file\": \"src/git.ts\",\n  \"results\": [\n    { \"file\": \"src/store.ts\", \"count\": 1 },\n    { \"file\": \"src/types.ts\", \"count\": 1 },\n    { \"file\": \"test/git.test.ts\", \"count\": 1 },\n    { \"file\": \"test/store.test.ts\", \"count\": 1 },\n    { \"file\": \"test/test-helpers.ts\", \"count\": 1 }\n  ]\n}\n```\n\n![Running graphkeeper query co-change with --json for a script-consumable answer, then graphkeeper query calls without graphify installed showing the graceful not-available explanation instead of a crash](./docs/usage.gif)\n\n## Features\n\n- **Mines real commit history, not a static snapshot.** `graphkeeper build`\n  runs `git log --no-merges --name-only` across the full history of the\n  repo and counts every file pair that changed together in the same\n  commit. There's no guessing at coupling from folder structure or import\n  statements alone; the answer comes from how the codebase actually got\n  edited over time.\n- **`--max-files-per-commit` protects the signal.** A single vendoring\n  commit or mass reformat that touches 400 files would otherwise pollute\n  every pair in that commit. The default cap (100 files) skips commits\n  above that threshold so real coupling doesn't drown in noise.\n- **Optional call-graph enrichment, never required.** When\n  [graphify](https://github.com/Graphify-Labs/graphify) is on `PATH`,\n  `graphkeeper build` shells out to its local `graphify extract\n  --code-only --no-cluster` and merges the resulting symbol/call edges into\n  the same store, unlocking `graphkeeper query calls`. Without graphify,\n  GraphKeeper still works in co-change-only mode and says so plainly\n  instead of failing.\n- **Every command has a `--json` mode.** `graphkeeper query co-change\n  <file> --json` and the equivalents return machine-readable output, so an\n  agent's calling code parses a real data structure instead of scraping\n  text.\n- **Two from-scratch implementations, one schema.** The npm package\n  (`src/`, TypeScript) and the PyPI package (`python/src/graphkeeper/`,\n  Python) are independent ports, not a wrapper of one around the other.\n  Both read and write the same `.graphkeeper/graph.json`, so a store built\n  with one CLI is queryable from the other.\n- **Every subprocess call uses an argv array, never a shell string.** Git\n  and graphify are both invoked through `spawnSync`/`subprocess.run` with\n  a list of arguments, so a crafted commit message or filename in the repo\n  being analyzed can't be interpreted as shell syntax.\n\n## CLI Reference\n\n```\nUsage: graphkeeper [options] [command]\n\nOptions:\n  -V, --version           output the version number\n  -h, --help              display help for command\n\nCommands:\n  build [options] [path]  Mine git history for co-change and (if available)\n                          merge in graphify's symbol/call graph\n  query                   Query the GraphKeeper store built by\n                          `graphkeeper build`\n  help [command]          display help for command\n```\n\n### `graphkeeper build [path]`\n\nWalks `path` (default: current directory), runs `git log --no-merges\n--name-only` across the whole history, and counts how often each pair of\nfiles was touched in the same commit. Writes the result to\n`.graphkeeper/graph.json`.\n\n| Option | Description |\n|---|---|\n| `--json` | emit machine-readable JSON instead of human-readable text |\n| `--max-files-per-commit <n>` | skip commits touching more than this many files (default: 100), keeping a single mass-reformat or vendoring commit from drowning out real co-change signal |\n| `--no-graphify` | skip graphify enrichment even if graphify is installed |\n\nIf [graphify](https://github.com/Graphify-Labs/graphify) is detected on\n`PATH`, `build` also runs `graphify extract <path> --code-only --no-cluster`\n(graphify's own headless, local, no-API-key AST extraction path) into a\ndirectory inside `.graphkeeper/`, and merges its nodes/edges into the same\nstore. The build output always states plainly whether that enrichment was\nincluded, and why it was skipped if not.\n\n### `graphkeeper query co-change <file>`\n\nLists files that historically changed alongside `<file>`, ranked by how many\ncommits touched both.\n\n| Option | Description |\n|---|---|\n| `--json` | emit machine-readable JSON instead of human-readable text |\n| `--limit <n>` | cap the number of results |\n| `--graph <path>` | path to a specific `graph.json` (default: `<cwd>/.graphkeeper/graph.json`) |\n\nExit code `0` when results are found, `1` when there's no co-change data for\nthat file yet, `2` on a usage or filesystem error.\n\n### `graphkeeper query calls <symbol>`\n\nShows callers and callees of `<symbol>`, using graphify's `calls` edges from\nthe most recent `build`. Only meaningful when that build included graphify\nenrichment; if it didn't, this prints a clear explanation of why instead of\na crash or a silent empty result.\n\n| Option | Description |\n|---|---|\n| `--json` | emit machine-readable JSON instead of human-readable text |\n| `--graph <path>` | path to a specific `graph.json` (default: `<cwd>/.graphkeeper/graph.json`) |\n\nExit code `0` when the symbol is found, `1` when it isn't (or enrichment\nwasn't available), `2` on a usage or filesystem error.\n\n## MCP Server\n\nGraphKeeper ships a [Model Context Protocol](https://modelcontextprotocol.io) server so an AI\ncoding agent (Claude, Cursor, or any MCP-compatible client) can mine co-change history and query\nthe graph directly, without a human invoking the CLI by hand.\n\nInstall the extra:\n\n```bash\npip install \"graphkeeper-cli[mcp]\"\n```\n\nAdd it to your MCP client's config (for Claude Desktop, `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"graphkeeper\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"graphkeeper-cli\", \"graphkeeper-mcp\"]\n    }\n  }\n}\n```\n\nThe server exposes one tool, `run`, that shells out to the published `graphkeeper-cli` npm package\n(via `npx graphkeeper-cli`) with the given subcommand and arguments plus `--json`, and returns the\nparsed JSON result:\n\n```\nrun([\"build\", \".\"])\nrun([\"query\", \"co-change\", \"src/git.ts\"])\n```\n\nTransport is stdio, so there is nothing to host: the MCP client spawns the server as a local\nsubprocess. Source: [`python/src/graphkeeper/mcp_server.py`](python/src/graphkeeper/mcp_server.py).\n\n## Library API Reference\n\nBoth packages expose a real importable surface, listed below. The command\nline is a thin wrapper over the same functions.\n\n### TypeScript / JavaScript (`graphkeeper-cli` on npm)\n\n```ts\nimport { build, queryCoChange } from \"graphkeeper-cli\";\n\nconst result = build(\".\");\nconsole.log(`${result.store.commitsAnalyzed} commit(s) analyzed`);\n\nconst coChange = queryCoChange(result.store, \"src/git.ts\");\nfor (const row of coChange.results) {\n  console.log(row.count, row.file);\n}\n```\n\n| Export | Signature |\n|---|---|\n| `build` | `build(targetPath: string, options?: BuildOptions): BuildResult` |\n| `queryCoChange` | `queryCoChange(store: GraphKeeperStore, file: string, options?: { limit?: number }): CoChangeQueryResult` |\n| `queryCalls` | `queryCalls(store: GraphKeeperStore, symbol: string): CallsQueryResult` |\n| `findGraphifyNode` | `findGraphifyNode(nodes: GraphifyNode[], symbol: string): GraphifyNode \\| null` |\n| `normalizeFileArg` | `normalizeFileArg(store: GraphKeeperStore, file: string): string` |\n| `detectGraphify` | `detectGraphify(): { installed: boolean; version: string \\| null }` |\n| `runGraphifyEnrichment` | `runGraphifyEnrichment(repoRoot: string): GraphifyEnrichment` |\n| `mineCoChange` | `mineCoChange(repoPath: string, options?: { maxFilesPerCommit?: number }): CoChangeMiningResult` |\n| `GitError` | Error subclass thrown on a git-related failure |\n| `resolveRepoRoot` | `resolveRepoRoot(targetPath: string): string` |\n| `readStore` | `readStore(repoRoot: string, overridePath?: string): GraphKeeperStore` |\n| `writeStore` | `writeStore(repoRoot: string, store: GraphKeeperStore): string` |\n| `PathSafetyError` | Error subclass thrown when a resolved path escapes the repo root |\n| `graphFilePath` | `graphFilePath(repoRoot: string): string` |\n\nTypes (`GraphKeeperStore`, `CoChangeEdge`, `GraphifyNode`, `GraphifyEdge`,\n`GraphifyRawGraph`, `GraphifyEnrichment`, `BuildOptions`, `BuildResult`,\n`CoChangeQueryResult`, `CallsQueryResult`) ship as `.d.ts` declarations\nalongside the compiled output; no separate generated docs site exists yet.\n\n### Python (`graphkeeper-cli` on PyPI)\n\n```python\nfrom graphkeeper import build, query_co_change\n\nresult = build(\".\")\nprint(f\"{result.store.commits_analyzed} commit(s) analyzed\")\n\nco_change = query_co_change(result.store, \"src/git.py\")\nfor row in co_change.results:\n    print(row.count, row.file)\n```\n\n`graphkeeper.__all__` exports: `build`, `query_co_change`, `query_calls`,\n`find_graphify_node`, `normalize_file_arg`, `detect_graphify`,\n`run_graphify_enrichment`, `mine_co_change`, `unquote_git_path`, `GitError`,\n`resolve_repo_root`, `read_store`, `write_store`, `graph_file_path`,\n`PathSafetyError`, plus the `GraphKeeperStore`, `CoChangeEdge`,\n`GraphifyNode`, `GraphifyEdge`, `GraphifyEnrichment`, `BuildOptions`,\n`BuildResult`, `CoChangeQueryResult`, `CoChangeResultRow`, and\n`CallsQueryResult` dataclasses. Same names as the TypeScript export table\nabove, in `snake_case`. No separate generated docs site exists yet; the\ndocstring at the top of `python/src/graphkeeper/__init__.py` covers the\nsame ground as this section.\n\n## Comparison\n\n| | GraphKeeper | graphify | GitNexus | Greptile | Augment Code |\n|---|---|---|---|---|---|\n| What it does | Mines `git log` for file-level co-change | Symbol/import/call-graph extraction via tree-sitter, AI-assistant skill | CLI + MCP tools (native, local) with an optional no-install browser/WASM mode; structural + call-flow analysis | Hosted AI code review with a graph-indexed codebase | Hosted AI coding platform with a live code dependency graph (Context Engine), plus commit-history and docs indexing |\n| Local-only? | Yes, always | Yes, for code parsing (docs/media indexing calls a backend if configured) | Yes for the CLI/MCP path; the browser mode runs client-side but needs the hosted web app | No by default; self-hosted/air-gapped is available on the Enterprise tier only | No; cloud-hosted, no self-host option publicly documented |\n| Free/OSS? | Yes, Apache-2.0 | Yes, Apache-2.0 | No, PolyForm Noncommercial 1.0.0 | Free Starter tier (1 seat, 50 credits/month), not open source | Not publicly documented as free; enterprise sales-led pricing |\n| Co-change mining? | Yes, this is the whole tool | No | No | No | No |\n| GraphKeeper's relationship | -- | GraphKeeper enriches its own store from graphify's local `extract` output when graphify is installed; doesn't reimplement it | Different delivery model (CLI+MCP+optional browser app vs. this project's plain CLI); no co-change mining | Team/PR-review focused, hosted product, not a local single-agent tool | Enterprise coding-assistant platform, not a standalone local CLI |\n\n(\"Not publicly documented\" is used instead of a guess anywhere a competitor\ndoesn't publish the number. Verified against each project's own README,\npricing page, or public site as of August 2026.)\n\n## What Is GraphKeeper, and Why Does It Exist\n\nGraphKeeper is a local CLI and library, published to both npm and PyPI as\n`graphkeeper-cli`, that mines `git log` for file-level co-change: which\nfiles have historically been edited in the same commit as a given file.\nIt writes that data to a single JSON file, `.graphkeeper/graph.json`, and\nanswers queries against it with no network calls.\n\nIt exists because an AI coding agent working solo on a codebase it doesn't\nalready know well has no fast way to answer \"what else usually changes\nwhen I touch this file?\" without running its own `git log --name-only`\nscan and tallying the results by hand, every time it's asked. GraphKeeper\nprecomputes that answer once and makes it queryable, including in a\n`--json` form a script or agent can parse directly.\n\nGraphKeeper does not reimplement symbol or call-graph extraction.\n[graphify](https://github.com/Graphify-Labs/graphify) (100K+ GitHub stars,\nApache-2.0, `pip install graphifyy`) already does that across 36\ntree-sitter grammars and ships as a slash-command skill for Claude Code,\nCursor, Codex, Gemini CLI, GitHub Copilot, and 15+ more assistants (20+\ntotal). When graphify is on `PATH`, `graphkeeper build` shells out to its\nlocal `graphify extract --code-only --no-cluster` and merges the result\ninto the same store, unlocking `graphkeeper query calls`. Without graphify,\nGraphKeeper still works, in co-change-only mode, and says so directly\ninstead of failing.\n\n## How It Works\n\n1. `graphkeeper build` runs `git log --no-merges --name-only` (via a safe\n   argv-array subprocess call, never a shell string) across the whole\n   repo history.\n2. For every commit, it counts every pair of files that changed together.\n   Commits touching more than `--max-files-per-commit` files (default 100)\n   are skipped, so a single vendoring or mass-reformat commit can't drown\n   out real signal.\n3. If `graphify` is detected on `PATH`, GraphKeeper also runs\n   `graphify extract <path> --code-only --no-cluster`, graphify's own\n   local, no-LLM, no-API-key extraction mode, into a directory inside\n   `.graphkeeper/`, then merges its `nodes`/`edges` into the same store.\n4. The merged result is written once, atomically, to\n   `.graphkeeper/graph.json`.\n5. `graphkeeper query` reads that file back and answers co-change or\n   call-graph questions against it. No network calls, ever.\n\n## Security\n\n- Every `git` and `graphify` invocation uses an argv array passed directly\n  to the OS (`spawnSync` in TypeScript, `subprocess.run` with a list in\n  Python), never a shell string, so commit messages, file names, or repo\n  paths can't be interpreted as shell syntax.\n- `.graphkeeper/` output paths are checked against the resolved repo root\n  before every write (symlinks included, via `fs.realpathSync`), so a\n  maliciously crafted repo can't redirect GraphKeeper's writes outside\n  `.graphkeeper/`.\n- No telemetry, no network calls, no secrets. The only files GraphKeeper\n  reads are `git log` output and, optionally, graphify's own `graph.json`;\n  the only file it writes is `.graphkeeper/graph.json`.\n\nSee [SECURITY.md](./SECURITY.md) for the vulnerability reporting process.\n\n## FAQ\n\n**Is GraphKeeper a general codebase knowledge-graph indexer?**\n\nNot on its own. `graphkeeper build` mines `git log` for file-level\nco-change and writes those edges to `.graphkeeper/graph.json`. That file\nonly becomes a symbol/call graph too if graphify is installed and gets\nmerged in during the same build. Without graphify on `PATH`, the store\nholds co-change data only, and `graphkeeper query calls` says so directly\ninstead of returning an empty result.\n\n**What does GraphKeeper actually give an agent that grep or git log don't?**\n\nA pre-computed, queryable answer to \"which files change together here,\"\nso an agent doesn't have to run its own `git log --name-only` scan and\ntally the results by hand on every question. `--json` on every command\nmakes that answer script-consumable rather than something a human has to\nread and re-type.\n\n**How do I install it, and does it work on Windows?**\n\n`npm install -g graphkeeper-cli` (Node.js 18+) or `pip install\ngraphkeeper-cli` (Python 3.9+); both need `git` on `PATH`. Neither\npackage contains OS-specific branches or native bindings, and the PyPI\nlisting is classified `Operating System :: OS Independent`, so it runs\nthe same way on Windows, macOS, and Linux anywhere git and a supported\nNode or Python runtime are available.\n\n**How is this different from graphify, the tool it links to for enrichment?**\n\nThey answer different questions. graphify extracts symbols, imports, and\ncall graphs straight from source via tree-sitter, across 36 languages;\nGraphKeeper mines commit history for which files were historically\nedited together, a signal graphify has no reason to compute. GraphKeeper\nshells out to graphify's own local `extract` command when it's present\nand merges the result in, rather than reimplementing tree-sitter parsing\nfrom scratch. Neither replaces the other; see the Comparison table above\nfor how GitNexus, Greptile, and Augment Code differ from both.\n\n**What actually breaks GraphKeeper, or gives an empty result?**\n\nTwo real cases, both documented, neither a crash: a shallow git clone\n(GitHub Actions' default `fetch-depth: 1`) has no history to mine, so\n`build` reports `0 commit(s) analyzed` and writes an empty co-change\ngraph; full history (`fetch-depth: 0`) is required. Separately,\n`query calls` only returns results if the most recent `build` ran with\ngraphify on `PATH`; if it didn't, the command explains that plainly\n(`graphify was not found on PATH...`) instead of pretending the symbol\ndoesn't exist.\n\n**Is it safe to run against a repo I don't fully trust?**\n\nEvery `git` and `graphify` call goes through an argv array straight to\nthe OS (`spawnSync` / Python's `subprocess.run` with a list, never a\nshell string), so filenames or commit messages can't be interpreted as\nshell syntax. Every `.graphkeeper/` write is checked against the\nresolved repo root, symlinks included, before it happens. There are no\nnetwork calls anywhere in the tool, so nothing about the repo you point\nit at leaves your machine.\n\n**Is the npm CLI just a wrapper around the Python one, or vice versa?**\n\nNeither. They're two independent, from-scratch implementations (`src/`\nfor TypeScript, `python/src/graphkeeper/` for Python) that happen to\nagree on the same `.graphkeeper/graph.json` schema, the same subcommands,\nflags, and exit codes. A store built by one can be read by the other.\nThe Python port's own test suite (ported from the TypeScript vitest\nsuite) is 78 tests, run against a real subprocess CLI invocation, not a\nmock of the other language's output. Both suites pass in a clean install\nas of this writing: 78/78 on the TypeScript side (`npm test`), 78/78 on\nthe Python side (`pytest`).\n\n**What license is this under, and can I use it commercially?**\n\nApache License 2.0, for both the npm and PyPI packages, with no dual\nlicensing and no separate commercial tier. That permits commercial use,\nmodification, and redistribution, with attribution and the standard\nApache patent grant. See [LICENSE](./LICENSE) for the full text.\n\n## Contributing\n\nIssues and PRs welcome. To build the TypeScript package from source:\n\n```bash\ngit clone https://github.com/RudrenduPaul/GraphKeeper.git\ncd GraphKeeper\nnpm install\nnpm run build\nnpm test\nnpm run lint\nnpm run typecheck\n```\n\nFor the Python package, see [`python/README.md`](./python/README.md). Full\ncontribution guidelines covering both codebases are in\n[CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\n[Apache License 2.0](./LICENSE)\n",
  "bytes": 23447,
  "sha": "d509db41b502a97ba7a8cf3807c385772ddae985131987cbbe65c2189f928740",
  "repo_slug": "rudrendupaul/graphkeeper",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rudrendupaul_graphkeeper_fbf613a2/readme"
}