context-graph.nvim

A Neovim plugin that intelligently gathers code context for feeding to LLMs (Large Language Models). It creates a "Symbol-centric Context Graph" by analyzing your code through multiple collectors, helping you provide relevant context when discussing code with AI assistants.

Features

• Comprehensive Context Collectors:

  • Selection: Captures your visual selection
  • Diagnostics: Includes LSP diagnostics and errors
  • Types: Follows type definitions via LSP with fallback patterns
  • Call Graph: Traces function calls and relationships (LSP + pattern fallback)
  • Dataflow: Tracks variable usage and definitions with type information
  • Dataflow TreeSitter: Enhanced dataflow analysis using TreeSitter
  • Git: Shows actual git diffs and blame info
  • Blame: Detailed git blame with commit info
  • Jump History: Recent navigation history
  • Search History: Recent search patterns
  • TODOs: Collects TODO/FIXME comments
  • Undo Tree: Shows undo/redo activity
  • Tests: Finds test blocks and results
  • Dependencies: Extracts imports and dependencies
  • Package Info: Project metadata from package.json, Cargo.toml, etc.

• Smart Token Budget Management: Estimates token usage and stays within configured limits

• Preview UI: See collected context before copying

• Preset Configurations: Quick, Medium, and Deep analysis modes

Installation

Using lazy.nvim:

{
  "winterfell/context-graph.nvim",
  dependencies = {
    "lewis6991/gitsigns.nvim", -- Optional: for git context
  },
  config = function()
    -- Plugin loads with sensible defaults
    -- Custom configuration is optional
  end
}

Using packer.nvim:

use {
  "winterfell/context-graph.nvim",
  requires = {
    "lewis6991/gitsigns.nvim", -- Optional: for git context
  }
}

Usage

Quick Start

The plugin provides three preset modes:

• Quick (300 tokens): Selection + Diagnostics
• Medium (800 tokens): Quick + Types + Dataflow
• Deep (2000 tokens): All collectors enabled

Keymaps

Visual Mode (copy to clipboard):

• <leader>as - Quick snapshot
• <leader>aS - Medium snapshot
• <leader>aD - Deep snapshot

Normal/Visual Mode (preview window):

• <leader>ap - Quick preview
• <leader>aP - Medium preview
• <leader>aA - Deep preview

Commands

:ContextGraph [quick|medium|deep]  " Show preview (default: medium)
:ContextGraphCopy [quick|medium|deep]  " Copy to clipboard

Preview Window

In the preview window:

• <CR> - Copy content to clipboard
• q or <Esc> - Close preview

Configuration

require('context_graph').setup({
  -- Token budget for different depths
  max_tokens = {
    quick = 300,
    medium = 800,
    deep = 2000,
  },
  
  -- Collector-specific settings
  max_call_depth = 3,      -- How deep to trace function calls
  max_type_depth = 3,      -- How deep to follow type definitions
  
  -- Preview window dimensions
  preview_height = 30,
  preview_width = 100,
})

Custom Usage

For advanced usage, you can call collectors directly:

local context_graph = require('context_graph')

-- Custom preset
local custom_preset = {
  name = "custom",
  depth = "medium",
  budget = 1500,
  list = { "selection", "types", "git" },
  preview = true  -- Show in preview window
}

context_graph.collect(custom_preset)

How It Works

1. Context Collection: When triggered, the plugin runs the specified collectors based on your preset
2. Token Budget: Each collector's output is checked against the token budget
3. Assembly: Results are combined, with duplicate content removed
4. Output: Final context is either copied to clipboard or shown in preview

Collectors in Detail

Smart Code Context:

• Selection: Captures visually selected text with proper indentation
• Types: Follows type definitions across files (LSP or pattern matching)
• Call Graph: Shows incoming/outgoing function calls (LSP with pattern fallback)
• Dataflow: Enhanced variable tracking with type information
• Dataflow TreeSitter: Deep AST-based variable flow analysis

Dynamic Evidence:

• Diagnostics: Formats LSP errors and warnings with line numbers
• Tests: Finds test blocks in code and test results in terminals
• Git: Shows actual diffs, not just stats
• Blame: Line-by-line git blame with author and commit info

Activity & Intent:

• Jump History: Shows where you've been navigating
• Search History: Recent search patterns (indicates what you're looking for)
• Undo Tree: Recent editing activity
• TODOs: Collects TODO/FIXME/NOTE comments

Project Intelligence:

• Dependencies: Extracts imports/requires across languages
• Package Info: Reads package.json, Cargo.toml, pyproject.toml, etc.

Requirements

• Neovim 0.8+ (for LSP support)
• Optional dependencies:
  • LSP server for your language (enhances types/callgraph collectors)
  • Git (for git/blame collectors)
  • TreeSitter parser (for dataflow_treesitter collector)

Token Estimation

The plugin estimates tokens using a 4-character-per-token heuristic, which works well for mixed code/English content. Each line counts as at least 1 token to account for newlines.

Contributing

Contributions are welcome! The plugin is designed to be extensible:

1. Create a new collector in lua/context_graph/collectors/
2. Add it to the collector map in assemble.lua
3. Write tests in tests/

License

MIT License - see LICENSE file for details

Acknowledgments

Inspired by the need to efficiently share code context with AI assistants while respecting token limits.