CodeGraph See demo

MVP · MIT · Built for a real developer pain point

The
decision memory layer for your codebase

Turn code structure, history, and design decisions into one queryable graph. Not just who changed a line — why it exists.

60-second demo CLI commands
  • tree-sitter parsing
  • Local SQLite graph store
  • Git time travel
  • Decision provenance

01 — Problem

Developers keep asking: why is this code written this way?

Existing tools each answer one slice. None of them connect the answers into one queryable chain.

git blame

Tells you who changed a line — not why it changed, or which constraints shaped it.

GitHub search

Text only. PR threads sink after a few years and retrieval becomes expensive.

ADR tools

Require manual writing. Docs drift from code; coverage stays incomplete.

AI coding assistants

Usually see only the current file — not historical constraints or rejected alternatives.

02 — Solution

Three layers, one graph

Parse code with tree-sitter into AST relations (uses / defined_by) and store them in a local SQLite database, then overlay the Git timeline and decisions from PRs, issues, and ADRs. Query any historical snapshot of the code graph — or the decision behind a single line.

Input Source repository Python / TypeScript
Input Git history commit · blame · diff
Input Decision sources PR · Issue · ADR
Parse tree-sitter AST · uses · defined_by
Extract Decision extractor reason · alternatives · status
Store SQLite CodeNode · Edge · Decision
Serve CLI · Web · AI context why / graph / export
01

Time travel queries

codegraph graph --at 2024-06-01 returns the structure at that moment — not today’s HEAD.

02

One line → decision provenance

codegraph why file:line emits a decision card: reason, rejected alternatives, source commit, and whether the record is a decision or only history.

03

Conflict detection

codegraph conflicts finds contradictory accepted decisions so rules do not fight each other.

03 — Demo

One “why” in the terminal

Simulated codegraph why output. The real CLI supports --help and full JSON.

codegraph — why

04 — Command contract

Eight core commands

Stable interfaces first. Every command supports --help.

codegraph index <path>

Parse code + ingest Git history + write the graph

--depth · --full · --json
codegraph why <file>:<line>

Return the decision provenance card for that line

core
codegraph graph --at <date>

Return the code graph at a point in time (JSON)

--scope
codegraph decisions --file <path>

Return the decision evolution timeline

--timeline
codegraph conflicts --scope <path>

Detect contradictory decisions

status conflicts
codegraph export --for-ai

Export an AI-agent context pack

--scope
codegraph serve

Start the local web visualization

Cytoscape.js
codegraph diff <from> <to>

Decision changes between two versions

--format json

05 — Graph model

Three entity types; relations are the answers

The schema is a core contract. Changes require a migration plan and explicit confirmation.

CodeNode Structure
  • kind function / class / …
  • file_path source location
  • valid_from/to validity window
  • uses reference edges
  • decided_by → Decision
Decision Decision
  • content what was decided
  • reason why
  • alternatives what was rejected
  • status accepted / superseded
  • tier decision / event
  • justifies → CodeNode
Edge Relation
  • from_uid source node
  • to_uid target node
  • kind uses / contains
  • defined_by → CodeNode

How this relates to existing tools

Today you usually pick one of three

  • Static code graphs Joern · CodeQL
  • Decision records ADR tools
  • Git time travel code-nexus

CodeGraph integrates them natively

  • Structure + decisions + timeline
  • Multi-hop joins on one graph
  • One interface for CLI / Web / AI

06 — Stack

Strict defaults. No silent swaps.

If a choice looks wrong, explain why and get confirmation before changing it.

Layer Choice Notes
Code parsingtree-sitterMulti-language AST, latest stable
StorageSQLiteone local file, no server
CLIPython + TyperPython 3.10+
VisualizationCytoscape.jsLocal web graph view
Optional LLMOllamaLocal-first
Qualitypytest · ruff · mypyover 80% coverage, 207 tests
DeliveryGitHub Actionslint · types · tests

07 — One line

CodeGraph: the decision memory layer

Rescue the “why” from sunk threads and hang it back on the exact line it justifies.

Back to demo View graph model