Documentation

Complete reference for all ContextDigger features

What is ContextDigger?

ContextDigger is context governance infrastructure for AI assisted development. It discovers focus areas in your repo, enforces Context Aperture and Attention Budgets, and maintains governed context bundles that developers and AI tools can reuse across sessions.

It is intentionally designed from the perspective of Autistic Intelligence: we assume that both humans and models are brilliant under the right constraints and fragile under overload. In practice, this means ContextDigger treats context as a scarce resource to be curated and governed, not an infinite window to be filled.

✓ Works with Your AI Stack

ContextDigger is a CLI first tool that exports governed context bundles for modern assistants like ChatGPT, Claude, Gemini, Copilot, Cursor, Windsurf, Aider, Cody, Codeium, and others. Run commands in your terminal to create context files, then instruct your AI tool to use .cdg/context/<area>.txt as the primary source of truth (for example: “Read .cdg/context/backend-api.txt and apply these changes inside this scope only.”).

Key Capabilities:

✓ Auto-Discovery: Automatically finds and organizes code areas
✓ Context Preservation: Never lose your place while coding
✓ Team Collaboration: Share knowledge and track activity
✓ Analytics: Understand your codebase deeply

High-Level Architecture

ContextDigger is designed as a context governance layer that sits between your codebase and your AI tools. The core idea is simple: discover focus areas, enforce budgets and policies, build governed context bundles, and let everything else consume those bundles.

Surfaces

contextdigger CLI - primary interface. Creates and manages focus areas, continuation contracts, and governed context bundles under .cdg/.
ContextDigger Native Core - a high-performance Rust library that implements all governance logic, discovery algorithms, and MCP protocols. Built for extreme speed and safety.
MCP Server - exposes ContextDigger capabilities (areas, context, contracts, governance, insights, provenance) as MCP tools and resources for coding assistants that speak the Model Context Protocol.
VS Code Extension - a graphical front end that visualizes focus areas, budget status, contracts, insights, and metrics on top of the same governed context model.

Data Flow (Simplified)

You run a CLI command (or an MCP tool / VS Code command).
The internal API loads state from your .cdg/ directory.
Budgets, policies, and authz are applied (Autistic Intelligence lens: respect limits).
A governed context bundle is assembled (files + provenance + budget status).
Your AI tools read from that bundle instead of scanning the repo directly.

This architecture keeps the governance logic in one place and lets different surfaces (CLI, MCP, VS Code, skills) share the same understanding of what the AI is allowed to know. All of them call the same internal API and pass through the same budget and refusal checks. For surface specific details, see the pages on the VS Code extension, the MCP server, and local models.

🆕 Multi-Strategy Sub-Area Creation

Transform Attention Budget Constraints into Guided Workflows

When an area exceeds the attention budget, ContextDigger analyzes your files with 4 parallel strategies and suggests focused sub-areas. Create the perfect sub-area in 30 seconds - no manual pattern writing required!

🤖 Multi-Strategy Analysis (NO AI)

When you hit an attention budget limit, ContextDigger analyzes your files using 4 parallel strategies - all using regex and pattern matching, no LLM calls:

1. Directory Strategy

Groups files by parent directory at depths 1-3

src/models/*, src/controllers/*

2. Naming Pattern Strategy

Finds common CamelCase/snake_case components

AccountTest*, OpportunityTest*

3. Role-Based Strategy

Groups by file role (test, model, controller, view, util, config)

All test files, All models

4. Import Relationship Strategy

Clusters files by import patterns and dependencies

Files importing 'auth'

⚡ Interactive Refusal Workflow

When an area exceeds budget, the refusal becomes interactive:

$ /dig salesforce-apex-tests

❌ ERROR: Area too large (176 files > 15 files budget)

📊 Sub-Area Analysis: 4 suggestions found

┌─ apex-account-tests (23 files) ✓

│ Strategy: naming | Confidence: 95%

├─ apex-opportunity-tests (34 files) ⚠️

├─ apex-lead-tests (19 files) ✓

└─ apex-contact-tests (15 files) ✓

Options:

1. Select sub-area to create and dig

2. Show more details (horizontal view)

3. Show tree view (hierarchical)

Your choice: 1

✓ Created sub-area: apex-account-tests

✓ Now digging: apex-account-tests (23 files)

Result: From attention budget constraint to focused exploration in 30 seconds!

🎛️ Dual Verbosity System

Control the level of detail with verbosity flags:

Compact (default)

/dig-split area

Shows top 4 suggestions with basic info

Horizontal -v

/dig-split area -v

File previews, patterns, metadata

Vertical Tree -vv

/dig-split area -vv

Hierarchical tree with nested splits

Example: Hierarchical tree view with -vv

apex-tests (176 files - TOO LARGE)

├─ apex-account-tests (23 files) ✓

│ ├─ apex-account-unit-tests (12 files) ✓

│ └─ apex-account-integration-tests (11 files) ✓

├─ apex-opportunity-tests (34 files) ⚠️

│ ├─ apex-opp-unit-tests (18 files) ✓

│ └─ apex-opp-integration-tests (16 files) ⚠️

└─ apex-lead-tests (19 files) ✓

🚀 Three Creation Methods

1. Auto-Suggest on Constraint (Recommended)

Context aperture exceeded → Interactive workflow → Focused sub-area in 30 seconds

/dig large-area

2. Manual Split Command

Proactively split large areas with multi-select

/dig-split area [-v|-vv]

3. Quick Create with Pattern

Create sub-area with exact glob pattern

/create-subarea parent name "pattern"

📊 File Intelligence Extraction

ContextDigger extracts rich metadata from your files without reading content or using AI:

✓ Purpose: Extracted from docstrings and top comments
✓ Role Detection: test, model, controller, view, util, config
✓ Import Analysis: Regex extraction of import statements
✓ Naming Components: CamelCase/snake_case splitting
✓ Framework Hints: Language-specific pattern detection

🔒 Privacy First: All analysis runs locally using pattern matching. Zero LLM calls, zero tokens consumed, zero external API requests.

🎯 AI Context Governance

Transform from navigation to governance

ContextDigger enforces budget limits, refuses oversized contexts, and generates machine readable scope definitions. These features work with modern assistants like ChatGPT, Claude, Gemini, Copilot, Cursor, Aider, Cody, Codeium, and any other coding tool that can read text bundles.

📊 Attention Budget System

Every code area shows its Attention Budget usage to prevent context overflow:

$ contextdigger dig tests

Budget: 3/15 files, 557/3,000 lines (19%)

📄 Context file: .cdg/context/tests.txt

✓ Default limits: 15 files, 3,000 lines
✓ Warning threshold at 80% usage
✓ Configurable via .cdg/config.json

🚫 Context Aperture Control

ContextDigger refuses to load oversized areas and suggests focused alternatives. With the new Rust core, this analysis is near-instant, even on massive repos.

$ contextdigger dig large-area

❌ ERROR: Area too large (6,926 lines > 3,000 lines budget)

Suggested sub-areas:

1. core/ (8 files, 1,234 lines)

2. utils/ (6 files, 892 lines)

✓ Enforces budget limits with exit code 1
✓ Automatically suggests smaller sub-areas
✓ Forces intentional decisions about scope

📄 Context File Export

Every dig command generates an AI-readable context file that works with any tool:

# ContextDigger Context: tests

# Budget: 3/15 files, 557/3,000 lines

## Files to Load

1. tests/test_integration.py (207 lines)

2. tests/test_focus_area.py (198 lines)

3. tests/test_discovery.py (152 lines)

✓ Works with assistants like ChatGPT, Claude, Gemini, Copilot, Cursor, Aider, Cody, Codeium
✓ Plain text format, no special protocols
✓ Includes budget status and bookmarks

Supported AI Assistants & Integration Patterns

ContextDigger is CLI first and tool agnostic. It prepares governed context bundles that work with modern assistants like ChatGPT, Claude, Gemini, Copilot, Cursor, Aider, Cody, Codeium, and others. The assistant you use becomes a client of the governed context you export.

Chat Assistants (ChatGPT, Claude, Gemini)

Generate a bundle with contextdigger dig <area> and open .cdg/context/<area>.txt.
Paste the bundle into a chat session, or upload it as a text file if the UI supports uploads.
Give a clear instruction like: “Use only this context file when making changes; do not reach outside this scope.”

IDE Assistants (Copilot, Cursor, Windsurf)

Keep the context file open in a pinned tab so the assistant treats it as part of the active context.
In tools like Cursor or Windsurf, reference the bundle file explicitly (for example by name or using their @file notation) when prompting.
Ask the assistant to explain and modify only the files listed in the bundle, not the entire workspace.

CLI/Terminal Tools (Aider)

Run ContextDigger first to generate the governed bundle for your area.
Start Aider in the same repo and add the bundle file (e.g. with a command like /add .cdg/context/<area>.txt).
Use the bundle to guide Aider’s edits and commits, keeping changes inside the governed slice.

Search Centric Tools (Cody, Codeium)

Open the context file in the editor so Cody and Codeium see it as a first class file in the project.
Reference the bundle in chat (“use the governed bundle at .cdg/context/<area>.txt as your primary source”).
Use their search or graph features to cross check that changed files are limited to those listed in the bundle.

Future friendly integrations

Because ContextDigger exports plain text bundles with clear budgets and file lists, it works well today via copy and paste and open tabs, and it is also ready for deeper integrations (such as MCP style tools or custom plugins) without changing the bundle format.

Installation

⚡ Quick Install (Recommended)

Install or update ContextDigger (current documented version: vlocal-dev) with a single command:

$ curl -sSL https://contextdigger.com/install.sh | bash

This installs the native ContextDigger binary. Works for both fresh installs and upgrades. You can optionally install editor or chat integrations (such as Claude skills) on top.

📋 Manual Installation (Alternative)

Step 1: Install Binary

$ curl install.sh | bash

Step 2 (Optional): Install chat/IDE skills

# Example: install Claude skills bundle for ContextDigger

$ curl -o - "https://raw.githubusercontent.com/ialameh/contextdigger/main/install-skills.sh" | bash

Step 3: Verify Installation

$ contextdigger --version

ContextDigger vlocal-dev

Feature Areas

1. Discovery & Navigation

Auto-discover code areas, navigate with precision, bookmark locations

/init-dig /dig /redig /mark-spot /goto-spot

2. History & Context

Browser-like navigation, snapshots, breadcrumbs, suggestions

/dig-history /dig-back /dig-forward /save-context /load-context /dig-suggest

3. Team Collaboration

Team presence, knowledge sharing, wiki generation

/dig-team /dig-note /dig-wiki

4. Code Intelligence

Dependencies, impact analysis, hotspots, coverage

/dig-deps /dig-impact /dig-hotspots /dig-gaps

5. Analytics & Insights

Work tracking, productivity metrics, reporting

/dig-analytics /dig-dashboard /dig-stats /dig-report

Supported Languages & Frameworks

Auto-Detected Languages:

Python

pytest, unittest frameworks

JavaScript / TypeScript

Jest, Vitest, Mocha test frameworks

Salesforce

Apex, Lightning Web Components

React Ecosystem

Next.js, Astro, React

Markdown & Scripts

Shell scripts, documentation

Any Language!

Works universally with pattern detection

Works with any language! Auto-detection provides enhanced features (better area names, framework-specific metadata), but ContextDigger functions with any codebase through pattern-based analysis.

Project Structure

After running /init-dig, ContextDigger creates a .cdg/ directory:

your-project/
└── .cdg/                      # ContextDigger data directory
    ├── config.json            # Project configuration
    ├── .gitignore             # Excludes user-specific data
    ├── areas/                 # Discovered code areas (commit these!)
    │   ├── backend-api.json
    │   ├── frontend-components.json
    │   └── ...
    ├── sessions/              # Exploration history (gitignored)
    │   └── .json
    └── bookmarks/             # Marked locations (gitignored)
        └── bookmarks.json

✅ Commit to Git

✓ .cdg/areas/ - Share discoveries with team
✓ .cdg/config.json - Project settings

❌ Don't Commit (Personal)

✗ .cdg/sessions/ - Personal history
✗ .cdg/bookmarks/ - Personal bookmarks

Real-World Examples

Example 1: Large Monorepo Navigation

Working on a large monorepo with multiple services and shared utilities:

# Initialize and discover all services

/init-dig

# Discovers: auth-service, payment-api, admin-dashboard, mobile-app, shared-utils

/dig payment-api

# Context: Now focused on payment processing

/mark-spot stripe-integration

# Bookmarks: payments/stripe/webhook_handler.py:45

# Days later...

/goto-spot stripe-integration

# Instantly: Back to payments/stripe/webhook_handler.py:45

Example 2: Bug Investigation Workflow

Tracking down a bug that spans frontend and backend:

/dig backend-api

# Found the bug in the backend

/mark-spot bug-location

# Bookmark the problematic code

/dig frontend-components

# Check how frontend calls this API

/goto-spot bug-location

# Jump back to fix the bug

/dig-history

# Review your investigation path

Example 3: Onboarding New Team Member

Help new developers understand the codebase quickly:

/init-dig

# Areas automatically discovered and documented

/dig-dashboard

# Overview of entire codebase

/dig authentication

# Start with critical systems

/dig-team

# See who owns what areas

/dig-note "Ask Sarah about auth flow"

# Document learning discoveries

Troubleshooting

"ContextDigger not initialized" error

Solution: Run /init-dig in your project directory first.

This creates the .cdg/ directory and discovers your code areas.

"ModuleNotFoundError: No module named 'contextdigger'"

Solution: Install the Python package:

pip3 install --user contextdigger

"/init-dig command not found"

Solution: Install Claude Code skills:

curl -o - "https://raw.githubusercontent.com/ialameh/contextdigger/main/install-skills.sh" | bash

Or use the one-line installer:

pip install contextdigger

"Discovery finds 0 areas"

Possible causes:

Very small project (< 5 files)
All files in gitignore
Unusual project structure

Solution: Manually create areas or adjust exclude patterns in .cdg/config.json

"contextdigger: command not found" (CLI)

Solution: Add Python user bin to PATH:

# macOS/Linux

export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to make permanent

Quick Start

1. Install package & skills
2. Run /init-dig in project
3. Use /dig to navigate
4. Mark spots with /mark-spot

Stats

Commands: 80

Strategies: 4

Code: 20,000+ lines

Dependencies: 0

View All Commands Installation Guide 📚 View Tutorial

Product Roadmap

From context management to context-free code intelligence

v1.3.2 CURRENT

Multi-Strategy Sub-Area Creation

Released December 2025 - Transform attention budget constraints into guided workflows

✓ Multi-Strategy Analysis - 4 parallel strategies (directory, naming, role, imports) using regex/patterns (NO AI)
✓ Interactive Constraints - Context aperture exceeded → 5 interactive options → Focused sub-area in 30 seconds
✓ Dual Verbosity System - Compact (default), horizontal (-v), vertical tree (-vv) with hierarchical splits
✓ File Intelligence - Extract purpose, role, imports, naming components without AI (pattern matching only)
✓ Three Creation Methods - Auto-suggest on constraint, manual split command, quick create with pattern
✓ Impact: Transform "error" to "focused workflow", zero tokens consumed, <50ms analysis for 45 files

v1.1.0

AI Context Governance

Released December 2025 - Transform from navigation to governance system

✓ Attention Budget System - Track file/line counts, enforce limits (default: 15 files, 3,000 lines)
✓ Context Aperture Control - Enforce constraints on oversized areas, suggest focused sub-areas
✓ Context File Export - Generate AI-readable context files for Claude Code, Cursor, ChatGPT, Copilot
✓ PyPI Release - Simple pip install contextdigger installation
✓ Impact: Universal AI tool compatibility, enforced context discipline, zero token overhead

v2.0 COMING Q1-Q2 2026

AST Symbol Indexing

Goal: Eliminate context window limits with offline local indexing

🔍 Symbol Indexing

• Tree-sitter AST parsing
• Index classes, functions, methods
• Build call graphs automatically
• Track imports & dependencies
• SQLite local storage

⚡ Instant Queries

• /find-symbol - Go to definition
• /find-references - Find all usages
• /show-callers - Call hierarchy
• /show-dependencies - Imports graph
• All queries <50ms, zero tokens

🎯 Impact: Context-Window Independence

Before (v1.1)

Limited by 200k token context

Grep searches load content

Slow on large codebases

After (v2.0)

Handle 10M+ lines easily

Query local index (zero tokens)

Sub-second responses

Language Support

Python, TypeScript, JavaScript

Dart, Apex (Salesforce)

Go, Rust coming in v2.1

Pricing: FREE for all users - validates feature value

v2.5 COMING Q2-Q3 2026

Team Collaboration Features

Goal: Launch paid Team tier with cross-project intelligence

🔗 Cross-Project Search

Search symbols across all team repos

👥 Shared Indexes

Team members see same indexed code

📊 Team Analytics

Productivity metrics & insights

💰 Pricing: Team Tier

$15/user/month for teams of 5-50 developers

ROI: Save 2+ hours/day per developer = $24k/month value for $75/month cost

v3.0 COMING Q3-Q4 2026

Vector DB Semantic Search

Goal: AI-powered semantic code search

🧠 Semantic Queries

• "Find code that handles JWT authentication"
• "Show me similar authentication patterns"
• Code similarity detection (find duplicates)
• Smart documentation (usage examples)

⚙️ Technical Approach

• Local embedding generation (CodeBERT)
• FAISS vector database
• Runs offline (privacy-first)
• Incremental updates

💰 Pricing Tiers

• Free: 5 semantic searches per day

• Team ($15/mo): 100 searches per day + cross-project

• Enterprise ($40/mo): Unlimited + private embeddings

v3.5+ FUTURE

Enterprise & Platform Expansion

🏢 Enterprise Features (v3.5)

• Security pattern detection
• Compliance scanning (GDPR, HIPAA)
• Self-hosted deployment
• SOC 2 Type II certification
• Audit logs & governance

🚀 Platform Expansion (v4.0)

• Cursor support (10x market size)
• VS Code extension
• Public API
• Plugin marketplace

Technical Architecture

Local Storage (No Cloud)

• SQLite for symbol index
• FAISS for vector embeddings
• All data stays on your machine
• Optional team sync via PostgreSQL

Performance Targets

• Index 100k lines in <30 seconds
• Query response <50ms
• Index size <50MB for 1M lines
• Incremental updates <5 seconds

Choose Your Workflow