🕸️ Graphify — Codebase Graph & AI Context Builder

Graphify your entire codebase into an interactive AST Knowledge Graph, generate dependency-aware AI prompts & Git diffs, and draft commits — 100% self-contained.

Select a file, symbol, Git diff, or your entire repository. AI Context Builder & Graphify analyzes the codebase using deterministic compiler ASTs, builds an interactive Knowledge Graph (PageRank "God Nodes", circular dependency cycles, and domain clusters), and generates authoritative, AI-ready Markdown prompts.

Graphify Knowledge Graph • VS Code Extension Guide • Supported Languages • CLI Quickstart • Architecture

🕸️ Graphify: Codebase Knowledge Graph & Interactive Visualizer

Give ChatGPT, Claude, Copilot, and DeepSeek a complete mental model of your entire repository—without installing external Python packages or wasting 100,000+ tokens.

Graphify Interactive Codebase Knowledge Graph Canvas

Built directly into the extension with zero external dependencies, Graphify scans your entire codebase across 20+ languages and produces:

Interactive Force-Directed Knowledge Graph in VS Code:
- Click Graphify: Codebase Knowledge Graph... in the Activity Bar Sidebar (or run Graphify: Build Interactive Knowledge Graph & AI Architecture Map).
- ★ God Node Detection (PageRank Centrality): Automatically highlights core architectural hubs and bottlenecks that the rest of the codebase depends on.
- ⚠ Circular Dependency Detection (Tarjan's SCC Algorithm): Surfaces exact file-level dependency cycles.
- ● Git Modified Overlay: Highlights uncommitted files directly inside the architecture graph.
- Click-to-Inspect & Jump to Code: Click any node to inspect its exported AST symbols, incoming callers (Used By), and outgoing imports (Depends On), double-click to open the file, or click ✨ AI Prompt to generate context for that node.
Token-Efficient AI Architecture Map (codebase-knowledge-graph.md):
- Compresses an entire codebase's architecture into a single queryable Markdown document (~85%–96% token savings compared to raw files) with an embedded Mermaid Architecture Flowchart (```mermaid), God Nodes table, circular cycle report, and full AST symbol & adjacency map.

🔌 VS Code Extension Guide

Generate clean, dependency-aware AI prompts directly inside your editor with single-click ease.

Graphify Activity Bar Sidebar

Streamlined Category Popup Wizard

How to Use

Right-click any source file in the Explorer or Editor (or open the Graphify — Codebase Graph & AI Context Builder icon in the left Activity Bar) and click Graphify: Codebase Graph & AI Context....

The interactive flow guides you through 3 clearly organized action categories:

🕸️ Category 1: Graphify Knowledge Graph (Visual Architecture & Codebase Map)

Entire Codebase Knowledge Graph (Primary #1) — Indexes the entire repository, computes PageRank God Nodes, detects circular dependency cycles, and launches the interactive visual graph canvas + saves the compact AI Architecture Map (codebase-knowledge-graph.md).
Entire Codebase Graph + <filename> Code Context (Merged) (New in v2.3.8) — Macro architecture map of the entire repository + full source code implementations strictly for the active file and its direct dependencies.
Merged: Graphify Architecture + Full Source Code — The ultimate AI prompt: combines the high-level Graphify macro architecture map (Mermaid diagram, God Nodes, cycle report) with the full source code implementations of all analyzed classes.
Single File Subgraph (<filename>) — Isolates and renders strictly the selected file and its direct/transitive callers and dependencies.
Entire Codebase + Highlight Uncommitted Git Changes — Visualizes the whole repo and illuminates all modified/uncommitted files in emerald green.
Entire Codebase + Include Test Files — Includes unit & integration test specs and fixtures.

📄 Category 2: AI Prompt & Context Builder (Code & AST Dependencies for LLMs)

Active File: Dependencies Only (No Git Changes) — Fast 1-click prompt: extracts AST dependency tree and full class implementations of the selected file.
Active File: Git Diff + Dependencies Tree — Includes staged/unstaged changes for this file plus upstream/downstream context.
Entire Codebase Graph + <filename> Code Context (Merged) — Embeds whole-repo Mermaid architecture flowchart and God Nodes table right before the full source code blocks of the active file.
Merged: Graphify Architecture + Full Source Code — Embeds Mermaid architecture flowchart and God Nodes table right before the full source code blocks of all files.
Symbol at Cursor + Dependencies — Automatically discovers the class/method at your cursor and extracts its focused dependency tree.
Entire Workspace / Project Scope — Traces dependencies starting from the project boundary.

🌿 Category 3: Workspace Git Scopes & Commit Tools

All Git Changes (Staged + Unstaged) + Dependencies Tree — Discovers all modified/added source files and traces their combined dependencies.
Staged Git Changes ONLY (git diff --cached) — Discovers only staged files and traces their dependencies.
Unstaged Git Changes ONLY (git diff) — Discovers only unstaged working tree modifications.
Compare Branch / Pull Request... — Compare against main, develop, or origin and trace dependency trees of all PR-touched files.
Last X Commits... — Select last 1, 2, 3, 5, or custom N commits and trace touched files.
Draft Git Commit Message... — Conventional Commit message generator powered by AST rules or built-in model.

Step 2: Instant Defaults vs Custom Options

Export with Defaults — Instant 1-click generation with automatic token budget and comments preserved.
Custom Options... — Fine-grained step-by-step configuration:
- Token Budget limits: Unlimited, 32k, 64k, 100k, 128k, 200k, or Custom.
- Comment Stripping: Preserve, Auto (strip only if over budget), or Remove.
- Traversal Depth: Unlimited, 1, 2, 3, 5, or Custom.
- Output Destination: Save to File, Copy to Clipboard, or Both.
- Language & Custom Prompt: Output in 10 languages (including isiZulu, English, Spanish, etc.) and pre-populate custom task instructions for the LLM.

2. Right-Click Inside Code (Targeted Symbol)

Place your cursor on any class name, interface, method, or function.
Right-click and choose AI Prompt: Generate from Symbol at Cursor.
Generates a focused prompt centered on that specific symbol and its required dependency tree.

3. Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)

Press Ctrl+Shift+P and type AI Prompt to see all available actions.
Choose AI Prompt: Generate with Options... to open an interactive QuickPick wizard to set:
- Token budget limits (e.g. 16k, 32k, 64k, 128k)
- Maximum traversal depth
- Comment stripping policy (Preserve, Remove, or Auto)
- Task description to pre-populate for the consuming AI

Commands Reference

Command	Title	Action
`aiPromptContextBuilder.graphifyCodebase`	Graphify: Build Interactive Knowledge Graph & AI Architecture Map	Builds the interactive force-directed Knowledge Graph & `codebase-knowledge-graph.md`
`aiPromptContextBuilder.generateFromFile`	Generate AI Prompt & Context	Opens the interactive Scope, Git Diff & Export popup
`aiPromptContextBuilder.draftCommitMessage`	Draft Git Commit Message (AST Rules / Built-in Model)	Drafts a Conventional Commit message from uncommitted changes & fills the Git box
`aiPromptContextBuilder.changeLanguage`	Change Language (EN / ES / FR / DE / ZH / JA / PT / RU / ZU / AF)	Switches Sidebar UI and AI response language across 10 languages
`aiPromptContextBuilder.generateFromSymbol`	AI Prompt: Generate from Symbol at Cursor	Centers analysis on the selected class/function symbol
`aiPromptContextBuilder.generateWithOptions`	AI Prompt: Generate with Options...	Opens interactive wizard for budget, depth, and comment policy
`aiPromptContextBuilder.generateAndCopy`	AI Prompt: Generate and Copy to Clipboard	Generates prompt and copies directly to clipboard
`aiPromptContextBuilder.generateAndSave`	AI Prompt: Generate and Save to File	Generates and saves directly to disk
`aiPromptContextBuilder.openLastGenerated`	AI Prompt: Open Last Generated Prompt	Re-opens the most recent context prompt in the editor
`aiPromptContextBuilder.showDependencyPreview`	AI Context: Show Dependency Preview	Displays an ASCII tree notification of discovered dependencies
`aiPromptContextBuilder.checkWorkers`	AI Context: Check Language Workers	Verifies compiler health across .NET Roslyn, Node.js, and Python

🎥 Adding Animated GIF Demos to the Marketplace & GitHub

The VS Code Marketplace and GitHub READMEs support animated .gif files natively! To show an animated walkthrough:

Record a short 5–10 second clip of yourself:
- Right-clicking a file in the VS Code explorer.
- Selecting AI Prompt: Generate from Current File.
- Showing the clean markdown prompt opening in the editor and pasting it into your AI chat.
Recommended Free Screen-to-GIF Tools:
- Linux: Peek (sudo apt install peek) or Kooha
- Windows: ScreenToGif (super clean editor)
- macOS: Kap or Gifski

Drop the GIF into docs/images/demo.gif and embed it in your README.md:

![AI Prompt Generator in Action](https://raw.githubusercontent.com/SitholeWB/ai-prompt-context-builder/main/src/extensions/vscode/docs/images/demo.gif)

Extension Settings (`aiPromptContextBuilder.*`)

Customize default behavior in Settings (Ctrl+, -> search aiPromptContextBuilder):

{
  "aiPromptContextBuilder.executablePath": "aipromptcontext",
  "aiPromptContextBuilder.defaultTokenBudget": null,
  "aiPromptContextBuilder.commentMode": "Preserve",
  "aiPromptContextBuilder.includeCompanionFiles": true,
  "aiPromptContextBuilder.includeTests": false,
  "aiPromptContextBuilder.includeGeneratedFiles": false,
  "aiPromptContextBuilder.openAfterGeneration": true
}

🚀 Why AI Context Builder?

When feeding code to LLMs (Claude, GPT, Gemini, DeepSeek) for refactoring, debugging, architecture reviews, or migrations, standard approaches fail:

Copy-pasting individual files leaves out essential interfaces, models, and constructor dependencies.
Dumping entire repositories blows through context limits and confuses the model with irrelevant noise.
Naive AI summarization tools truncate methods, replace real code with ellipses (// ...rest unchanged), and strip critical implementation details.

AI Context Builder solves this:

🛡️ Complete Source Files: Every included file is included in full. Never summarized, truncated, pseudo-coded, or replaced with ellipses.
📁 Preserve Original Relative Paths: Relative workspace paths (e.g. src/Application/Customers/CustomerService.cs) are preserved verbatim. Absolute paths are never exposed.
📄 One Output Artifact: The entire dependency-aware context lives in exactly one self-contained, beautifully formatted Markdown document (*-context.md).
⚖️ No Hidden Limits: When no token budget is specified, all eligible transitive dependencies are traversed without artificial depth or file-count caps.
🔒 100% Local & Private: Runs strictly locally. No source code upload, no external API keys required, and zero telemetry.

🌐 Supported Languages & Capability Matrix

Every analyzer explicitly discloses its capability level in the generated Markdown metadata:

Language / File Type	Extensions	Engine / Worker	Capability Level
C#	`.cs`	.NET Roslyn (`Microsoft.CodeAnalysis.CSharp`)	Semantic
Visual Basic .NET	`.vb`	.NET Roslyn (`Microsoft.CodeAnalysis.VisualBasic`)	Semantic
ASP.NET Core	`.cs`	Controller, Minimal API & DI Enhancer	Semantic
Blazor & Razor	`.razor`, `.cshtml`	Scoped CSS & Companion Code-Behind Enhancer	SyntaxAware + CompanionFile
TypeScript	`.ts`, `.mts`, `.cts`	TypeScript Compiler API 5.9.3	Semantic
JavaScript	`.js`, `.mjs`, `.cjs`	TypeScript Compiler API 5.9.3	Semantic
React	`.jsx`, `.tsx`	React Component, Hook & Context Enhancer	Semantic + SyntaxAware
Angular	`.ts`, `.html`, `.scss`	Angular `@Component`, `templateUrl`, `styleUrls`	Semantic + CompanionFile
Vue SFC	`.vue`	Single-File Component Parser (single file in output)	SyntaxAware
HTML	`.html`, `.htm`	HTML Syntax Analyzer (scripts, module scripts, styles)	SyntaxAware
CSS, SCSS, Sass	`.css`, `.scss`, `.sass`	SCSS & Sass Syntax Parser (`@import`, `@use`, partials)	SyntaxAware
Python	`.py`	Python 3 `ast` & `tokenize` Worker	Semantic
Java	`.java`	Java Syntax & Maven/Gradle Project Analyzer	SyntaxAware
Go	`.go`	Go Packages & `go.mod` Syntax Analyzer	SyntaxAware
JSON / YAML Config	`.json`, `.yaml`, `.yml`	Explicitly Referenced Configuration Analyzer	ImportGraph

💻 CLI Quickstart

Build the Solution

dotnet build

The compiled CLI wrapper is located at ./bin/aipromptcontext (with ./bin/aicontext and ./bin/aiprompt compatibility aliases).

Usage Examples

# 1. Analyze C# Service with unlimited token budget
./bin/aipromptcontext generate --file src/Application/Customers/CustomerService.cs

# 2. Analyze Angular Component with HTML template and SCSS partials
./bin/aipromptcontext generate --file src/app/customers/customer.component.ts --framework angular

# 3. Analyze React Component with a 64k token budget and auto comment stripping
./bin/aipromptcontext generate --file src/components/CustomerPage.tsx --max-tokens 64000 --comments auto

# 4. Analyze Python module and output machine-readable JSON metadata
./bin/aipromptcontext generate --file app/services/customer_service.py --format json

# 5. Check active language workers
./bin/aipromptcontext check-workers

Options Reference

Usage:
  aipromptcontext generate --file <path> [options]
  aipromptcontext check-workers

Required:
  --file <path>                  Target source file to analyze

Options:
  --workspace <path>             Workspace root directory boundary
  --project <path>               Explicit project file (.csproj, tsconfig.json, etc.)
  --symbol <qualified-name>      Specific class, function, or symbol to select as root
  --output <path>                Destination Markdown file path
  --max-tokens <int>             Token budget (omitted means unlimited)
  --max-depth <int>              Maximum dependency traversal depth (omitted means unlimited)
  --comments preserve|remove|auto Comment preservation policy (default: preserve)
  --language <lang>              Force specific language analyzer
  --framework <fw>               Force specific framework adapter
  --analysis-level <level>       Best, Semantic, SyntaxAware, ImportGraph
  --task <text>                  Custom prompt task heading
  --include-tests <bool>         Include test files (default: false)
  --include-generated <bool>     Include generated files (default: false)
  --include-attributes <bool>    Include attributes/decorators (default: false)
  --include-companions <bool>    Include companion templates/styles (default: true)
  --include-config <bool>        Include configuration files (default: true)
  --save <bool>                  Write result to file (default: true)
  --copy <bool>                  Copy result to clipboard (default: false)
  --format text|json             Output format (default: text)
  --omit-timestamp               Omit generation timestamp for deterministic golden testing
  --verbose                      Enable verbose diagnostic logging
  --help                         Display help message
  --version                      Display version information

🧩 Architecture

Visual Studio Code Extension / Visual Studio VSIX / CI / CLI
                             |
                             v
               Context Orchestrator CLI (`aicontext`)
                             |
             +---------------+---------------+
             |                               |
        Shared Core (.NET 10):          Workers (Language-Neutral Protocol):
        - Neutral Dependency Graph       - In-Process .NET Worker (C#, VB.NET, Razor, Blazor, Roslyn)
        - Upward Workspace Discovery     - Node.js Worker (TypeScript Compiler API 5.9, React, Angular, Vue, HTML, SCSS)
        - Deterministic Scoring Engine   - Python Worker (AST, tokenize, import analysis)
        - Token Budget Selector          - Java & Go Analyzers (Project metadata & syntax)
        - Secret Preflight Scanner
        - Safe Markdown Generator

The orchestrator is implemented in .NET 10 / C# for instant native CLI execution and in-process Roslyn semantic analysis, while dedicated workers communicate via standard I/O using a versioned JSON protocol (protocolVersion: "1.0").

🔒 Security & Privacy Guarantee

Zero Cloud Leakage: No remote AI API calls, telemetry, or external network requests.
Preflight Secret Scanner: Inspects candidate files before inclusion for private keys, AWS/Slack/GitHub keys, and database connection strings with passwords. Secret values are never printed to logs or Markdown files.
Path Traversal Protection: Canonicalizes all file paths and enforces strict workspace boundaries. Symlinks escaping the workspace and .git internals are automatically rejected.

🧪 Testing & Debugging

The repository features comprehensive automated acceptance tests and step-by-step developer debugging tools:

Run Acceptance Tests: dotnet run --project tests/AiPromptContextBuilder.Tests.csproj
VS Code F5 Debugging: Pre-configured .vscode/launch.json for stepping through CLI execution and tests.
Detailed Guide: See docs/testing-and-debugging.md for worker pipe debugging, AST inspection, and golden-file regression workflows.

📚 Documentation Index

👤 Author & Maintainer

Welcome Bonginhlahla Sithole
📍 South Africa, KwaZulu Natal
🔗 GitHub: @SitholeWB
📦 VS Code Marketplace: sitholewb

📄 License

Distributed under the MIT License.

Graphify — Codebase Graph & AI Context Builder

Welcome Bonginhlahla Sithole