repokg

Generate an AI-ready knowledge graph of any codebase — so an AI agent (or a new developer) can read one file and start building immediately.

repokg extracts everything that can be known deterministically about a repo — module inventory, internal import graph, every branch classified against every PR (merged / squash-merged / abandoned / stale), contributor stats, CI/Docker/Helm/Make surface — and renders it as:

• KNOWLEDGE_GRAPH.md — a single human/AI-readable document with a mermaid architecture graph, module tables, branch & PR catalog, timeline, and ops inventory.
• .repokg/kg.json — the same graph, machine-readable.

The semantic layer (module purposes, data-flow narratives, project eras, gotchas) can't be produced by static analysis without guessing — so repokg is agent-first: it emits .repokg/prompts/enrich.md, a rigorous prompt any AI coding agent (Claude Code, Cursor, Copilot Workspace…) executes to verify-and-fill the narrative sections, writing .repokg/narratives.json. Re-render and the knowledge graph is complete. No API keys, no LLM dependency in the tool itself.

Install

pipx install repokg        # or: pip install repokg
# from source:
pipx install git+https://github.com/NehharShah/repokg

Requirements: Python ≥ 3.9, git. Optional: gh (logged in) for the PR/branch cross-reference — without it the knowledge graph still builds, minus PR data.

Usage

cd your-repo
repokg                      # = generate: scan + prompts + render

Output:

.repokg/kg.json               # machine-readable knowledge graph
.repokg/prompts/enrich.md        # hand this to your AI agent
KNOWLEDGE_GRAPH.md                        # the knowledge graph document

Then, in your AI agent of choice:

Follow the instructions in .repokg/prompts/enrich.md

The agent explores the code, writes .repokg/narratives.json, and runs repokg render — KNOWLEDGE_GRAPH.md now carries verified purposes, data flows, timeline eras, and gotchas alongside the deterministic structure.

Commands

Flags: --out DIR (default <repo>/.repokg), --md FILE (default <repo>/KNOWLEDGE_GRAPH.md), --exclude PATTERN (repeatable), --no-github, --no-cache, --pr-limit N, --diff, --json.

Incremental scans

scan caches what it extracted from each file in .repokg/cache.json and replays it for files that have not changed, so a re-scan only parses what moved:

$ repokg scan .
cache: cold (no cache yet) — parsed 431 files
$ repokg scan .
cache: replayed 431 of 431 files, parsed 0
$ vim src/app.py && repokg scan .
cache: replayed 430 of 431 files, parsed 1

A file is replayed only when git has not flagged it — git diff against the commit the cache was written at, plus git status for anything dirty, staged, or untracked — and its size and mtime still match what was recorded. The second check is what covers the files git cannot speak for: anything in .gitignore that repokg still walks, submodule contents, or a directory that is not a git checkout at all.

The cache is an optimization and nothing else. Output is identical either way (a test enforces byte-for-byte equality), a missing or unreadable or unusable cache degrades to a full scan and says so on stdout, and --no-cache forces one. repokg clean removes it with everything else.

One caveat, shared with every build tool that trusts stat: a file rewritten with its size and modification time preserved is invisible to both checks. Use --no-cache if you have reason to think that happened.

Synthetic mixed Python/TypeScript/Java monorepos, one laptop, best of three — indicative only, not a benchmark suite (see #17):

The ratio grows with the repo because the saving is essentially the whole parse cost, while the warm floor does not shrink. That floor is worth knowing before optimising further: at 6,000 files it is roughly 100 ms of git metadata (branches, contributors, merge classification — none of which touches the cache) and 30 ms of walking, stat'ing and writing the output. Parsing, the part the cache removes, was around 1,150 ms of the cold scan.

Excluding paths

Common noise (node_modules, .git, build output, …) is skipped automatically. For repo-specific noise — fixtures, snapshots, vendored trees, generated docs — add globs on the command line or in a committed .repokgignore at the repo root:

repokg scan --exclude '*fixtures' --exclude 'docs/gen'

# .repokgignore — one glob per line, same semantics as --exclude
*fixtures
*.snap
packages/*/gen

Patterns are matched (fnmatch) against repo-relative paths; matching directories are pruned wholesale and matching files dropped, so modules, import edges, and ops all inherit the exclusion. * crosses /: *fixtures matches at any depth, fixtures only at the root. CLI patterns and .repokgignore are unioned. Exclusions are never silent — scan prints what it dropped, kg.json records the patterns and counts, and repokg audit carries an uncertainty note.

Honesty layer

Most of the graph is measured fact. The parts that are heuristics are labeled as findings with confidence and evidence, surfaced by repokg audit:

[git]
  trunk = master          high    detected via origin/HEAD symref
  integration = staging   medium  matched a well-known integration branch name
[modules]
  4 flagged generated     low     path-name heuristic; verify before excluding

Agent-written narratives.json is schema-validated before rendering — malformed enrichment fails loudly with errors precise enough for the agent to self-correct. (Findings/confidence design inspired by RepoCanon.)

Agent integration

repokg inject adds a managed block (delimited by <!-- repokg:begin/end -->, idempotent, never touches your hand-written content) pointing agents at KNOWLEDGE_GRAPH.md:

• CLAUDE.md (Claude Code) — updated if present
• AGENTS.md (the cross-tool agent standard) — updated if present, created if no agent file exists at all
• .github/copilot-instructions.md (Copilot) — updated if present
• .cursor/rules/repokg.mdc (Cursor, with alwaysApply: true) — created if .cursor/rules/ exists; falls back to legacy .cursorrules

Keep it fresh in CI:

- run: pipx run repokg check . || echo "::warning::KNOWLEDGE_GRAPH.md is stale"

KNOWLEDGE_GRAPH.md itself also lists any agent-context files it found, so an agent landing on the knowledge graph discovers your rules — and vice versa.

What gets extracted (all verified, never guessed)

Why agent-first instead of calling an LLM API?

Because the enrichment quality depends on reading the code, and your coding agent already has the repo open, tools to search it, and your permission model. A prompt it can execute beats a second LLM integration with its own keys, costs, and context limits. The contract between tool and agent is one JSON file (narratives.json) with a fixed schema — everything else stays deterministic and reproducible.

Known limitations

• JS/TS: relative imports, tsconfig/jsconfig paths/baseUrl aliases and workspace package names are resolved; extends chains are not followed (a leaf config without its own aliases is skipped rather than shadowing the root's), and package exports maps are not modeled — subpath imports fall back to the package dir. Alias imports whose targets ground nowhere are counted in an uncertainty note.
• Fork PRs: a fork PR whose head branch name matches a local branch will be linked to it (GitHub's API reports bare head refs).
• Python: packages are discovered at the repo root and under src/; deeper monorepo layouts (packages/*/src/…) get file-level edges only.
• Rust: use declarations only — macro-generated imports, re-export chains, and [dependencies] path = … (non-workspace) crates are not resolved; crate:: paths ground only in module dirs/files that exist.
• Java/Kotlin: explicit imports only — same-package references (no import needed) and fully-qualified inline names produce no edges; when a package is declared only in test roots, edges resolve there.
• Branch ahead counts use one batched git call on git ≥ 2.41, with a per-branch fallback on older git.
• Incremental scans cache per-file facts, not repo metadata: go.mod, Cargo.toml, tsconfig.json, package.json and pnpm-workspace.yaml are re-read every scan (one per package, against one read per source file).

Roadmap

• Rust import graph
• Java / Kotlin import graphs
• --exclude glob patterns + .repokgignore
• Incremental scan cache for large monorepos
• llms.txt emission alongside KNOWLEDGE_GRAPH.md
• tsconfig paths alias + workspace package resolution
• PyPI release + prebuilt GitHub Action

Development

pip install -e .
python -m unittest discover -s tests -v

No runtime dependencies — stdlib only.

Contributing

All work goes through issue → branch (issue-<N>/<desc>) → PR → review → squash-merge to main. See CONTRIBUTING.md for the workflow and the ground rules (zero deps, findings for heuristics, clean reversibility).

License

MIT