Frequently Asked Questions
Everything you need to know about ContextDigger
🚀 Getting Started
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 compiles governed context bundles that your AI tools can safely use.
You still use Claude, Cursor, Copilot, or ChatGPT. The difference is that they read .cdg/context/*.txt instead of scanning your entire repo ungoverned.
Do I need a specific AI tool to use ContextDigger?
No. ContextDigger is tool agnostic. Today you can use it with Claude, ChatGPT, Cursor, Copilot, or any other assistant by pointing them at the governed context bundles it creates (for example, .cdg/context/backend-api.txt).
We’re also exploring deeper integrations (like MCP/IDE plugins) so AI tools can request governed context directly, but the core governance layer works with whatever assistant you already prefer.
How do I install ContextDigger?
One command:
$ curl -sSL https://contextdigger.com/install.sh | bash This automatically installs the native binary and Claude Code skills. Works for both fresh installs and upgrades!
See Getting Started for detailed instructions.
What languages does ContextDigger support?
ContextDigger is language-agnostic! It works with any programming language including JavaScript/TypeScript, Python, Go, Rust, Java, C++, Ruby, PHP, and more. It discovers code areas based on file structure and common patterns rather than language-specific analysis.
How long does setup take?
Installation takes about 2 minutes. Running /init-dig for the first time
is near-instant (typically < 1 second for major repos). You'll be productive immediately after that!
✅ Do I need to approve commands every time?
No! ContextDigger runs without approval prompts. Commands execute instantly with zero interruption.
How it works:
ContextDigger uses a CLI-based architecture. When you run /dig-dashboard, it calls a simple bash command that Claude Code auto-approves. All the Python logic runs behind the scenes through your installed package.
What you'll experience:
- Instant execution - No "Do you want to proceed?" prompts
- Smooth workflow - Type command, get results immediately
- Just like native tools - Same experience as running git, npm, or any CLI tool
- Still secure - Commands run from your installed package, not arbitrary code
Technical Note: This is the recommended architecture for Claude Code skills - implement logic in a proper CLI package, keep skill files simple. It's faster, cleaner, and provides a better user experience.
🎯 v1.3.0: Sub-Area Creation & Intelligent Splitting
Everything about the new intelligent sub-area features
What happens when I hit an attention budget limit?
In v1.3.0, attention budget constraints are interactive! Instead of just stopping, ContextDigger analyzes your files and shows you multi-strategy sub-area suggestions.
Pick an option, select a sub-area, and you're back to work in seconds (not minutes).
What are the 4 splitting strategies?
1. Directory Grouping - Groups files by parent directory at depths 1-3
2. Naming Pattern Clustering - Finds common CamelCase/snake_case components (e.g., Account*, Opportunity*)
3. File Role Detection - Groups by role: test, model, controller, view, util, config
4. Import Relationship Analysis - Clusters files that import similar modules
All strategies run in parallel and results are deduplicated and ranked by confidence!
What does "file intelligence WITHOUT AI" mean?
ContextDigger extracts file metadata using regex and content patterns - no AI needed! It extracts:
- Purpose - From module docstrings and top comments
- Role - From file naming + content patterns (test, model, controller, etc.)
- Imports - From import statements
- Naming Components - From CamelCase/snake_case splitting
- Framework Hints - From detected import patterns (React, Django, etc.)
This happens instantly and locally - zero API calls, zero cost!
What are the verbosity levels (-v and -vv)?
Compact (default): Shows top 4 suggestions with basic info
Horizontal Verbose (-v): Shows detailed context per suggestion:
- File list preview (first 5-10 files with intelligence)
- Pattern details (include/exclude rules)
- Metadata (language, framework, parent area)
- File intelligence (purpose, role, imports)
Vertical Verbose (-vv): Shows hierarchical tree view:
- Full nested hierarchy with recursive splitting
- Box-drawing characters for tree visualization
- Budget status indicators (✓ / ⚠️) at each level
- Maximum depth 2 by default
When should I use `cdg split` vs auto-suggest?
Auto-Suggest (on refusal): When you try to dig into an oversized area
- Reactive - triggers automatically
- Quick - get suggestions and dig immediately
- Best for: First-time encounters with large areas
cdg split: When you want to explore options before creating
- Proactive - you control when it runs
- Exploratory - see all suggestions, pick multiple
- Best for: Planning ahead, creating multiple sub-areas at once
Can I create sub-areas with exact patterns?
Yes! Use cdg create-subarea for precise glob patterns:
Perfect for power users who know exactly what they want!
What if the suggestions aren't good?
You have options:
- Try different verbosity - Option 2 (horizontal) or 3 (tree view) might show better suggestions
- Use exact patterns -
cdg create-subareawith your own glob pattern - Manual area creation - Create a custom area definition in
.cdg/areas/ - Override budget - Option 4 (use with caution)
In practice, the strategies work well for most codebases. Directory + naming patterns catch 80%+ of use cases!
How fast is the analysis?
Extremely fast. Our migration to a native Rust core has yielded massive performance gains:
- Standard project: < 50ms
- Large repo (135k files): ~180ms
- Neural Refinement: Optimized local inference via Candle
File intelligence is cached, so subsequent analyses are even faster!
💡 Pro Tip: Hierarchical Workflow
Smart developers use hierarchical splitting:
- Run
cdg dig large-area- Hit budget, see top-level suggestions - Select a sub-area (e.g., "frontend-components-auth")
- If still too large, ContextDigger shows NESTED suggestions automatically
- Keep drilling down until you have a focused 15-file work area
This is like zooming into a map - start high-level, drill down to where you need to be!
💡 Usage & Features
What's the difference between /dig and /dig-search?
/dig <area-name> - Navigate to a specific discovered area (like "backend-api" or "frontend")
/dig-search <query> - Search across all areas, files, notes, and history
Use /dig when you know where you want to go, /dig-search when you're looking for something.
How do snapshots work?
Snapshots save your complete work context including:
- Current code area you're in
- Your bookmarks
- Navigation history
- Notes you've taken
Use /dig-snapshot name to save and /dig-load name to restore.
Perfect for handling interruptions or switching between features!
Can I use ContextDigger on multiple projects?
Absolutely! Each project gets its own .cdg/ directory.
You can run /init-dig in as many projects as you want.
Your snapshots, bookmarks, and history are project-specific.
Does it work with monorepos?
Yes! ContextDigger is excellent for monorepos. It automatically discovers different services, packages, and modules as separate areas. You can navigate between them seamlessly and understand cross-service dependencies.
How accurate is the dependency analysis?
ContextDigger uses static analysis to map imports/requires and file relationships. It's very accurate for understanding which files depend on each other. For dynamic dependencies (like runtime plugin loading), it shows you file-level relationships which are usually sufficient for planning changes.
👥 Team & Collaboration
Can my whole team use ContextDigger?
Yes! Every team member should install it. The .cdg/ directory
can be committed to git (it's just metadata), so everyone shares the same discovered areas.
Individual history, bookmarks, and snapshots are stored locally, but team notes and wiki are shared.
How does the team wiki work?
When you use /dig-note "your note", it's saved in
.cdg/notes/. Running /dig-wiki
generates a searchable wiki from all team notes. Commit the notes directory to share knowledge with your team!
Can I see what my teammates are working on?
Yes, use /dig-team to see team presence (who's in which code area, via git sync).
Use /dig-activity to see recent team activity.
Use /dig-who <area> to find the expert for a specific area.
🔧 Technical
Does ContextDigger modify my code?
No, never. ContextDigger only reads your code and creates a .cdg/
directory for metadata. It never modifies your source files.
What's stored in .cdg/?
- areas.json - Discovered code areas
- notes/ - Team notes and wiki content
- config.json - Project settings
- local/ - Your personal history, bookmarks, snapshots (gitignored)
Should I commit .cdg/ to git?
Yes, except for local/. The default .gitignore includes .cdg/local/
but commits the rest. This shares discovered areas and team notes while keeping personal history private.
Does it work with large codebases?
Yes! ContextDigger has been tested on codebases with 500k+ lines of code. Initial scan might take 30-60 seconds for very large projects, but after that, all operations are instant. It's actually MORE valuable for large codebases where manual navigation is painful.
Are there any dependencies?
Zero external dependencies! The core ContextDigger engine is written in pure Rust and compiles to a standalone binary. It no longer requires Python or any heavy runtime engines.
Is my code data sent anywhere?
No. ContextDigger runs entirely locally. Your code never leaves your machine. All analysis is done locally. The only network activity is when Claude Code itself operates (which is controlled by Anthropic, not ContextDigger).
💰 Pricing & Support
How much does ContextDigger cost?
It's free and open source! ContextDigger is released under the MIT license. You can use it for personal projects, commercial work, or anything else without paying.
Where do I get support?
Documentation: Complete documentation and guides
Tutorial: Step-by-step walkthrough
Commands Reference: Full command reference
🔮 Future Plans
Will it support Cursor / VS Code / other tools?
Yes! Support for Cursor and other AI coding tools is planned.
The architecture separates the Python backend from the interface, so adding new tool support is straightforward. Cursor support is the top priority after initial release stabilizes.
Will there be a GUI/web interface?
It's being considered! A web dashboard for visualizing code areas, dependencies, and analytics could be valuable for future releases.
What features are coming next?
✅ Recently Released (v1.1.0):
- Attention Budget System - Track file/line counts, enforce limits
- Context Aperture Control - Enforce constraints on oversized areas, suggest alternatives
- Context Export - Generate AI-readable context files for any tool
- PyPI Package - Simple
pip install contextdigger
🔮 Short-term roadmap:
- AST symbol indexing (context-free code intelligence)
- Cursor and VS Code support
- File provenance tracking (why each file was included)
- Continuation contracts (persist intent across sessions)
- Visual dependency graphs
Still Have Questions?
Check our comprehensive documentation and guides