Features

Structural analysis

• AST-parsed edges — imports, calls, inherits, implements, uses-type, and contains relationships, extracted via tree-sitter for TypeScript, TSX, JavaScript, and Python.
• Imports-only support — regex-based import extraction for CSS, C, C++, Go, Rust, Java, Lua, and PHP.
• Symbol-level nodes — toggle into functions, classes, methods, interfaces, and types as first-class graph nodes inside their containing files.
• TODO / FIXME visibility — files with TODO comments glow orange; files with FIXME comments glow red. Technical debt is visible at a glance.

Documentation protocol

• @see, @tested-by, @adr, @depends-on tags in code comments become typed graph edges connecting code to tests, decisions, and dependencies.
• @domain, @status, @author tags become node metadata for coloring, filtering, and hover tooltips.
• Note ↔ code links — markdown frontmatter related-code creates documents edges from notes to code, closing the loop between documentation and implementation.
• Seed domains command — one command discovers a domain vocabulary from your folder structure and stamps @file / @domain / @status headers into code files automatically.

Interactive graph

• Color modes — language, domain, status, or auto-detected community (label propagation reveals natural module boundaries).
• Zone-aura heatmap — soft colored glows behind nodes, driven by domain, community, or user-defined color groups.
• Color groups — query-based grouping with domain:, path:, ext:, kind:, status:, tag: prefixes or free-text substring.
• Node sizing — constant, lines of code, degree, fan-in, or fan-out.
• Neighborhood filtering — focus on a file and show only nodes within N hops.
• Dead-code highlighting — dim nodes with no incoming edges.
• Hover-focus spotlight — dim distant nodes/edges on hover to spotlight a node's neighborhood.

Edge types

Every edge below is produced automatically when code follows ordinary conventions — static imports, extends/implements, type annotations, and the @tag/[[wikilink]]/frontmatter protocol. Write idiomatic, well-documented code and the graph fills in. The first six edges come from the AST/regex parser; the rest come from the documentation protocol.

For per-edge optimization guidance — exactly what to write to maximize each edge honestly — see §5 Edge-maximization guide in the skill guide.

Node types

Nodes come in two layers. File-level nodes are always rendered; symbol nodes (shown when Show symbols is on) nest inside their containing file via contains edges.

Symbol nodes are available in Tier A languages only (TypeScript, TSX, JavaScript, Python). Tier B languages produce file-level nodes plus imports edges, and still fully support the @tag / [[wikilink]] / TODO / FIXME / frontmatter protocol. Node fill color follows the active Color mode: language (default), domain (@domain), status (@status), or auto-detected community. Symbol colors deliberately avoid blue, which is reserved for file nodes.

Each node also carries metadata the plugin surfaces: domain, status, author (hover tooltip), tags, todoCount/fixmeCount (orange/red glow), and lines/fan-in/fan-out (node sizing). Writing the @tags and frontmatter documented in the skill guide populates all of this automatically.

Quick start

1. Install — from Obsidian's community plugin browser, or manually copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/code-graph/.
2. Enable — in Settings → Community plugins.
3. Open — click the graph ribbon icon, or run Code Graph: Open graph view from the command palette.
4. Tag (optional) — run Code Graph: Seed domains from codebase to auto-tag your files with @domain / @status headers.

The documentation protocol

The plugin ships an AI-ready skill — skills/obsidian-code-graph/SKILL.md — that tells AI agents (and humans) exactly how to write code comments, file headers, and markdown frontmatter so the graph extracts maximum semantic value. Load it into your AI coding agent, or read it directly. When code adheres to the protocol below, the graph populates automatically — every @tag, [[link]], and frontmatter field becomes a typed edge or node attribute.

Install the skill into your AI agent (works with any agent that supports the skills.sh format — Claude Code, Cursor, OpenCode, and others):

npx skills add mrjw717/obsidian-code-graph -g -y

Or browse/list before installing: npx skills add mrjw717/obsidian-code-graph -l. The skill loads the full protocol — tag reference, per-edge and per-node optimization guidance, language matrix, and a domain auto-detection procedure — into any compatible agent.

Code files — Tier 1 header + typed links:

/**
 * @file Calculator engine — math expression evaluation
 * @domain calculator
 * @status stable
 * @author Josh
 *
 * @see [[Shunting Yard Algorithm]]
 * @tested-by [[engine.test.ts]]
 * @adr [[ADR-001-Calculator-Architecture]]
 * @depends-on [[MathEngine]]
 */

Markdown notes — frontmatter closes the code↔docs loop:

---
related-code:
  - "[[engine.ts]]"
domain: calculator
type: adr
status: accepted
tags: [calculator, architecture]
---

The skill guide contains the full tag reference, per-edge and per-node optimization guidance, the language support matrix, a domain auto-detection procedure for AI agents, and a verification checklist. Point your AI agent at it and it will detect your codebase's domains, offer them as suggestions, and document files to maximize graph edges.

Language support

The @tag / [[wikilink]] / TODO / FIXME / frontmatter protocol works in any language — only the structural edges differ. See the skill guide for details on adding a language to the full-structural tier.

Requirements

• Obsidian 1.7.2 or later.
• Desktop only. The plugin parses source with tree-sitter WASM grammars, which is a heavy, desktop-oriented workload that hasn't been validated on mobile. (isDesktopOnly: true in the manifest.)

Privacy & permissions

Code Graph is local-first. It makes no network requests and collects no telemetry — all parsing and graph rendering happen entirely inside your vault. The permissions it does use:

No file outside the vault is read or written.

Obsidian Sync note: main.js is ~5.8 MB because the tree-sitter grammars are embedded for self-contained installs. Obsidian Sync Standard (5 MB file cap) will not sync it — use Sync Plus or another sync method.

Each release ships with GitHub artifact attestations so main.js, manifest.json, and styles.css can be cryptographically verified against the source build.

Development

npm install      # install dependencies
npm run dev      # watch mode — rebuild on save
npm run build    # production build (tsc typecheck + esbuild minified)
npm run lint     # ESLint with eslint-plugin-obsidianmd
npm test         # vitest unit tests (27 tests)

Build pipeline

The build embeds the tree-sitter core runtime and 4 grammar WASM files as base64 directly into main.js, making the plugin fully self-contained. Fresh installs from a GitHub release need only main.js, manifest.json, and styles.css — no external downloads or manual extraction.

Release artifacts

main.js, manifest.json, and styles.css are attached to GitHub releases tagged with the version number. The release workflow automatically builds, attests, and publishes.