CodeDelta

Local-first, commit-aware structural code intelligence

Built on CodeGraph · commit-level diff, trace, panorama & wiki

CodeDelta answers “how did this codebase change over time?” by building a deterministic structural graph at each commit, then diffing, tracing, visualizing, and documenting from that graph — not from line diffs or text-chunk RAG alone.

	Capability	What you get
Δ	Delta View	Structural compare between two commits: symbols, edges, blast radius, impact score, file diff
🔍	Trace View	Natural-language questions → ranked candidate commits with verifiable evidence
◎	Panorama	Interactive call-flow graph at one commit (or delta-colored overlay)
📄	Wiki	Per-commit docs, Mermaid from real graph edges, optional LLM narration, Ask this repo

This repository is a fork: the CodeGraph engine lives under src/ (CLI + MCP + tree-sitter graph). The CodeDelta app lives under packages/ and apps/web/ (import, timeline, delta, trace, panorama, wiki, settings UI).

Architecture

Product flow

How the four views connect around a single imported repository and its commit history:

flowchart TB
  Import["Import repo\n(GitHub URL or local path)"]
  Timeline["Commit timeline\nbranch + history"]

  Import --> Timeline

  Timeline --> Delta["Delta View\nbase → head structural compare"]
  Timeline --> Trace["Trace View\nwhich commit introduced this?"]
  Timeline --> Panorama["Panorama\ncall-flow graph at one commit"]
  Timeline --> Wiki["Wiki\ngenerate docs + Ask"]

  Trace -->|"verify candidate"| Delta
  Delta -->|"Graph tab / drill-down"| Panorama
  Wiki -->|"symbol citations"| Panorama
  Wiki --> Ask["Ask this repo\nLLM + graph evidence whitelist"]

  Provider["Settings → Provider\n(Codex / OpenAI / none)"]
  Provider -.->|"optional narration"| Trace
  Provider -.->|"narration + Ask (required)"| Wiki

Project layout (technical)

flowchart TB
  subgraph Clients["Clients"]
    Web["apps/web\nReact UI"]
    Desktop["apps/desktop\nTauri 2 + bundled Node 22"]
  end

  subgraph Server["packages/codedelta-server"]
    API["REST API\nimport · compare · trace · wiki · panorama"]
  end

  subgraph Engines["Analysis engines"]
    Snap["snapshot-manager\nworktree + cache"]
    Diff["graph-diff · impact-score · delta-summary"]
    Sub["graph-subgraph\nPanorama layout"]
    Trace["trace-engine"]
    WikiEng["wiki-engine\nTOC · pages · Mermaid · Ask retrieval"]
    Prov["provider-runtime\noptional LLM"]
  end

  subgraph Core["src/ — CodeGraph"]
    CG["tree-sitter extract → SQLite\nexportGraph per commit"]
  end

  subgraph Cache[".codedelta/ (local)"]
    Repos["repos/ clones"]
    Snaps["snapshots/ per commit"]
    Wikis["wiki/ generated pages"]
  end

  Web --> API
  Desktop --> API
  API --> Snap
  API --> Diff
  API --> Sub
  API --> Trace
  API --> WikiEng
  API --> Prov
  Snap --> CG
  Snap --> Repos
  Diff --> Snaps
  Sub --> Snaps
  Trace --> Snaps
  WikiEng --> Snaps
  WikiEng --> Wikis
  Trace --> Prov
  WikiEng --> Prov

Wiki generation is DeepWiki-inspired but graph-grounded: TOC, diagrams, and citations come from CodeGraph snapshots; the LLM only adds narrated prose and Ask answers on top of a fixed evidence whitelist (no invented symbols or edges).

How CodeDelta differs from CodeGraph and Understand Anything

	CodeGraph	CodeDelta	Understand Anything
Primary question	What is the structure now? Who calls whom?	How did structure change between two commits? Which commit likely introduced a shift?	What does this repo mean? How do I onboard onto it?
Unit of work	Current workspace / indexed tree	`base commit → head commit` (+ commit-history trace)	Whole repo (or docs) snapshot
Output	MCP tools, callers/callees, context for agents	Delta summary, impact score, file diff, trace candidates + evidence, per-commit Wiki + Ask	Interactive graph dashboard, tours, plain-English node summaries
Analysis	Deterministic tree-sitter graph (SQLite)	Same graph per commit snapshot, then structural diff	Multi-agent pipeline + LLM-enriched graph (`.understand-anything/`)
AI role	Optional (agent uses graph via MCP)	Optional for Trace (deterministic path always works)	Central to explanations and tours
Best for	Day-to-day coding agents, refactors, “where is X?”	Release review, regressions, “when did this behavior start?”	Greenfield onboarding, architecture exploration

Use together: CodeGraph (or CodeDelta’s embedded engine) for live structure; CodeDelta when you care about history and commit-level risk; Understand Anything when you need a guided map of the whole repo for humans joining the project — not a substitute for commit-to-commit structural delta.

Features

Delta View

Compare two commits (Base = before, Head = after):

Changed symbols (functions, classes, components, routes)
Added/removed dependency edges (calls, imports)
Affected nodes from graph traversal
Deterministic impact score with severity and explanation
Delta summary (main areas, risks, suggested review order)
File-level unified diff modal (click files or symbols)
Per-snapshot metadata (codegraph vs fallback extraction)
Graph tab — React Flow call tree at the head commit with added/modified/removed coloring on nodes and edges

Panorama

Interactive call-flow graph from CodeGraph snapshots (React Flow):

Single commit — top entry routes/components/exported symbols, expandable by call depth
Branch + commit selectors; auto-rebuild when either changes
Drill-down — Expand from here, breadcrumb trail, Back / All entry points
Shareable URLs — ?branch=&commit=&depth=&focusPath= preserves your drill-down path
Export — SVG (vector) or hi-DPI PNG generated from graph data (not a DOM screenshot)
Optional LLM node labels (non-authoritative)
Linked from Delta View → Graph, Trace View, and Commit Timeline

Trace View

Describe a bug, behavior change, or question in natural language:

Rank candidate commits from history (messages, paths, symbols, delta signals)
Attach evidence per candidate (previous → candidate compare when a parent exists)
Return a direct answer, confidence, uncertainty, and suggested next steps
Jump to Delta View to verify each candidate
View in Panorama on a candidate commit (trace symbol highlights when available)

Without any LLM configured, Trace still returns candidates, evidence, and impact radius (evidence-first, no invented facts).

Wiki (graph-grounded docs + Ask)

Open Wiki from the commit timeline (or /repos/:id/wiki). Pick a commit → Generate wiki → browse the TOC, read pages, and use Ask this repo in the side panel.

Inspired by DeepWiki, but built on CodeGraph snapshots instead of embedding/RAG over raw files:

Layer	LLM required?	Content
Structure	No	TOC (overview, architecture, top modules, routes/components), symbol tables, file lists, README excerpts
Diagrams	No	Mermaid module import graph and call flows — serialized from real edges, never invented
Narration	Optional	Per-page prose when a provider is configured (“with LLM narration”)
Ask	Yes	Conversational Q&A; lexical + graph retrieval → evidence whitelist → LLM answer with citations

Citations link symbols to file/line ranges; symbol citations open Panorama at the right commit
Ask bootstraps entry points + README when your question does not match symbols directly
Cached under .codedelta/wiki/<repoId>/<hash>/<wikiVersion>/; generation is a background job with progress
Engine: packages/codedelta-wiki-engine/

Commit timeline & import

Import a public GitHub repo (owner/repo or URL) or a local git path
Browse commits; open Delta, Trace, Panorama, or Wiki from the timeline

What CodeDelta is not

Not a generic Git GUI — no merge UI or branch workflow
Not a line-diff-first tool — structural delta is the product; text diff supports review
Not a replacement for Understand Anything — no interactive whole-repo onboarding graph or LLM tours

Quick start

Requires Node.js 20–24 and git.

git clone https://github.com/ingeniousfrog/CodeDelta.git
cd CodeDelta
npm install
npm run build:codedelta
npm run dev:codedelta

Open http://localhost:3847 (dev mode proxies the Vite UI to the API port; http://localhost:5173 also works).

Import a repository (GitHub URL or local path)
Commit Timeline — pick a branch and browse history
Delta View — choose Base (before) and Head (after), then compare
Trace View — describe an issue; review candidates and open Delta to verify
Panorama — pick branch/commit and explore call trees; drill down from any entry or route
Wiki — pick a commit, generate the wiki, browse pages, and ask questions with cited answers

UI walkthrough

1) Import repository

2) Commit timeline

3) Delta View (structural compare)

4) Trace View (evidence-first origin analysis)

File-level modal details are also captured in: docs/images/delta-file-diff-modal.png

API: http://localhost:3847

Endpoint	Description
`GET /api/health`	Health check
`GET /api/repos/:id/compare?base=&head=`	Structural delta between commits
`GET /api/repos/:id/panorama?commit=&depth=&root=`	Call-flow graph at one commit
`GET /api/repos/:id/panorama?base=&head=&depth=`	Delta-colored call-flow graph (head commit tree)
`POST /api/repos/:id/panorama/enrich`	Optional LLM labels for panorama nodes
`GET /api/repos/:id/diff?base=&head=&file=`	Unified diff for one file
`POST /api/repos/:id/trace`	Trace question → candidates + evidence
`POST /api/repos/:id/wiki/generate?commit=`	Start wiki generation (background job)
`GET /api/repos/:id/wiki/status?commit=`	Generation state + progress
`GET /api/repos/:id/wiki/toc?commit=`	Wiki table of contents
`GET /api/repos/:id/wiki/page?commit=&section=`	One wiki page (markdown + citations)
`GET /api/repos/:id/wiki/asset?commit=&path=`	README / wiki image at commit (git show)
`POST /api/repos/:id/wiki/ask`	Question → cited answer over the commit graph
`GET /api/settings/provider`	Current LLM provider settings
`GET /api/settings/provider/codex-status`	Local Codex CLI login status

Configure Codex for Trace View & Wiki (optional)

CodeDelta can reuse your existing Codex CLI login — no API key pasted into the web UI.

1. Log in with Codex CLI

# Install Codex CLI if needed: https://github.com/openai/codex
codex login

This creates or updates ~/.codex/auth.json (ChatGPT OAuth). You can override the directory with CODEX_HOME.

2. Select Codex in CodeDelta

Open the app → Settings → Provider Settings
Choose Codex OAuth
Confirm the page shows that local login was detected (path under ~/.codex/)
Model — leave empty to use model from ~/.codex/config.toml, or override (e.g. gpt-5.5)
Save settings

3. Run Trace

Open Trace View, enter a concrete question (file paths, symbols, or config names help), and click Run trace.

Deterministic results always appear; if Codex is configured, the model may refine the narrative. Model output is non-authoritative — evidence and Delta verification are the source of truth. The same provider also powers Wiki page narration and Ask (Ask requires a provider; wiki pages still ship structurally without one).

Codex troubleshooting

Symptom	What to try
“auth.json not found”	Run `codex login` on the same machine as the CodeDelta server
`HTTP 400` / unsupported parameter	Restart `npm run dev:codedelta` after pulling latest (Codex backend ≠ OpenAI API)
`fetch failed` / timeout	Check network/VPN; retry; see error details for `ENOTFOUND` / `ETIMEDOUT`
AI box red but candidates look fine	Expected fallback — structural trace still works; fix Codex and rerun
Changes to provider code not applied	`dev:codedelta` rebuilds packages on start; restart the dev server

Other providers: No AI (default), OpenAI API key, or OpenAI-compatible base URL + key. Anthropic and Ollama are not implemented yet.

Local cache (`.codedelta/`)

Path	Purpose
`.codedelta/repos/<id>/`	Cloned or referenced repositories
`.codedelta/registry.json`	Import registry
`.codedelta/snapshots/<repoId>/<hash>/<analyzerVersion>/`	Per-commit structural snapshots
`.codedelta/wiki/<repoId>/<hash>/<wikiVersion>/`	Generated wiki (toc, pages, meta)
`.codedelta/settings.json`	Provider settings

Snapshots are built lazily on compare/trace — full history is not pre-indexed.

Extraction

Primary: CodeGraph (index + exportGraph) in an isolated git worktree per commit.

Fallback: Minimal TS/JS extractor if CodeGraph fails; snapshots record extractionMethod: "fallback" and warnings.

Built on CodeGraph

The src/ tree is the upstream CodeGraph project:

Tree-sitter → SQLite knowledge graph
CLI: codegraph init, codegraph sync, codegraph serve --mcp
MCP tools for agents (search, callers, callees, trace, impact)

Initialize CodeGraph in a repo when you also want agent-time MCP (separate from the CodeDelta web app):

npm run build
npx codegraph init -i

Project layout

src/                          # CodeGraph core (upstream-compatible)
packages/
  codedelta-types/
  codedelta-repo-manager/
  codedelta-server/           # REST API
  codedelta-snapshot-manager/
  codedelta-graph-diff/
  codedelta-graph-subgraph/   # Panorama call-tree + layout
  codedelta-impact-score/
  codedelta-delta-summary/
  codedelta-trace-engine/
  codedelta-wiki-engine/      # Wiki TOC/pages/Mermaid + Ask retrieval
  codedelta-provider-runtime/
apps/web/                     # React UI (Delta, Trace, Panorama, Wiki)
apps/desktop/                 # macOS desktop shell (Tauri 2)

Roadmap and deferred work: docs/codedelta/ROADMAP.md.

Limitations

TypeScript/JavaScript-first practical path today
Delta and trace: commit-to-commit only (no PR/branch/working-tree compare yet)
Codex: local CLI session only (no in-browser OAuth)
Panorama overview shows top entry surfaces only on large repos — drill down with Expand from here; sparse graphs often mean mount points (USE /api/*) need expansion to see router internals
Panorama export is a simplified card layout (no live Expand buttons); prefer SVG for zoom/clarity
Symbol click opens file diff, not symbol-to-hunk mapping

Desktop (macOS & Windows)

CodeDelta ships desktop apps (apps/desktop/) — Tauri 2 shells that bundle Node 22 (for CodeGraph’s node:sqlite) and the API server. End users do not need a separate Node install.

Version is read from apps/desktop/src-tauri/tauri.conf.json (currently 0.2.1). macOS and Windows installers publish to the same GitHub Release: codedelta-desktop-v0.2.1. Desktop bundles include Delta, Trace, Panorama, and Wiki (Ask requires a configured LLM provider). v0.2.0 was withdrawn — its macOS DMG used a manual packaging path and was ~40 MB larger with no functional benefit; use v0.2.1.

Download

Platform	File	Notes
macOS (Apple Silicon)	GitHub Releases → `CodeDelta_*_aarch64.dmg`	Unsigned; right-click → Open if blocked
Windows (x64)	GitHub Releases → `CodeDelta_*_x64-setup.exe`	NSIS installer
macOS mirror	百度网盘 · 提取码: `frog`	Legacy v0.1.0 only — no Wiki; use GitHub Releases for current builds

Install (macOS): open the dmg → drag CodeDelta to Applications.

If macOS says “is damaged and can’t be opened” after downloading from GitHub/Safari, that is Gatekeeper quarantine on unsigned apps — the app is not corrupt. Fix:

xattr -cr /Applications/CodeDelta.app

Then open again, or right-click the app → Open the first time. (Baidu Netdisk downloads often need the same xattr step.)

Install (Windows): run the setup .exe and follow the wizard.

Requires git on PATH on both platforms. Do not run npm run dev:desktop while using the installed app — both use port 3847; the dev server is API-only and causes a blank Cannot GET / page.

Runtime data: ~/Library/Application Support/CodeDelta (macOS) · %APPDATA%\CodeDelta (Windows)

Build from source

Requirements: target OS (macOS or Windows), Rust 1.88+, repo dev dependencies (npm ci). macOS also needs Xcode Command Line Tools; Windows needs NSIS for the installer.

# One-time: stage embedded Node + server runtime (~200MB under apps/desktop/src-tauri/resources/runtime/)
npm run stage:desktop

# Build .app + .dmg (unsigned; Gatekeeper may prompt on first open)
npm run build:desktop

# Dev: API + Vite + Tauri window (uses localhost:5173 + :3847, not bundled runtime)
npm run dev:desktop

Output:

macOS: apps/desktop/src-tauri/target/release/bundle/dmg/CodeDelta_*_aarch64.dmg
Windows: apps/desktop/src-tauri/target/release/bundle/nsis/CodeDelta_*_x64-setup.exe

apps/desktop/ layout:

apps/desktop/
  package.json              # tauri dev / build:app scripts
  src-tauri/
    tauri.conf.json         # window, bundle, embedded resources
    src/server.rs           # spawn bundled Node API on launch
    resources/runtime/      # generated by npm run stage:desktop (gitignored)

Git: the app shows a banner if git is missing.

Variable	Desktop default	Meaning
`CODEDELTA_CACHE_DIR`	`~/Library/Application Support/CodeDelta`	Cache root (set by Tauri)
`CODEDELTA_MONOREPO_ROOT`	bundled `runtime/app`	CodeGraph dist root
`CODEDELTA_STATIC_DIR`	bundled `runtime/web-dist`	Web UI static files
`CODEDELTA_DESKTOP`	`1`	Desktop mode flag

Development

npm run build:codedelta
npm run dev:codedelta    # API :3847, web :5173, watches provider-runtime

npm test -- packages/codedelta-graph-diff packages/codedelta-graph-subgraph \
  packages/codedelta-impact-score packages/codedelta-server \
  packages/codedelta-snapshot-manager packages/codedelta-trace-engine \
  packages/codedelta-wiki-engine packages/codedelta-provider-runtime \
  __tests__/codedelta

Environment variables:

Variable	Default	Meaning
`CODEDELTA_CACHE_DIR`	`.codedelta/`	Cache root
`CODEDELTA_PORT`	`3847`	API port
`CODEDELTA_MONOREPO_ROOT`	(monorepo root)	CodeGraph dist root; required for desktop bundle
`CODEDELTA_STATIC_DIR`	—	Serve web UI from this directory (desktop production)
`CODEDELTA_DESKTOP`	—	When `1`, default cache dir on macOS is Application Support
`CODEDELTA_SNAPSHOT_TIMEOUT_MS`	`120000`	Snapshot build timeout
`CODEDELTA_SNAPSHOT_MAX_NODES`	`50000`	Snapshot node cap

License

MIT — see LICENSE.

This repository combines:

CodeGraph (src/, CLI, MCP): Copyright (c) 2026 Colby Mchenry. Upstream: @colbymchenry/codegraph.
CodeDelta (packages/*, apps/web/): Copyright (c) 2026 ingeniousfrog and contributors.

Both parts are licensed under the same MIT terms. Redistributions should retain the copyright notice in LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 400 Commits
.claude		.claude
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
__tests__		__tests__
apps		apps
docs		docs
packages		packages
scripts		scripts
site		site
src		src
.gitignore		.gitignore
BUNDLING.md		BUNDLING.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
install.ps1		install.ps1
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

CodeDelta

Architecture

Product flow

Project layout (technical)

How CodeDelta differs from CodeGraph and Understand Anything

Features

Delta View

Panorama

Trace View

Wiki (graph-grounded docs + Ask)

Commit timeline & import

What CodeDelta is not

Quick start

UI walkthrough

1) Import repository

2) Commit timeline

3) Delta View (structural compare)

4) Trace View (evidence-first origin analysis)

Configure Codex for Trace View & Wiki (optional)

1. Log in with Codex CLI

2. Select Codex in CodeDelta

3. Run Trace

Codex troubleshooting

Local cache (.codedelta/)

Extraction

Built on CodeGraph

Project layout

Limitations

Desktop (macOS & Windows)

Download

Build from source

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Local cache (`.codedelta/`)

Packages