Step-by-Step Tutorial

Master ContextDigger in 30 minutes with this complete walkthrough

🎯 What You'll Learn

  • ✅ Install ContextDigger (Lesson 0)
  • ✅ Initialize ContextDigger in a project
  • ✅ Navigate code areas efficiently
  • ✅ Bookmark important locations
  • ✅ Track your exploration history
  • ✅ Understand code dependencies
  • ✅ Save and restore context
  • ✅ Document your discoveries
  • ✅ Use analytics to understand your codebase
  • ✅ Collaborate with your team

⏱️ Time Required: ~30 minutes

This tutorial uses a sample e-commerce project as an example. You can follow along with any codebase.

0

Installation & Prerequisites

Goal: Install ContextDigger and verify it's working

📋 Step 0.1: Check Prerequisites

Before installing, make sure you have:

  • ✓
    Python 3.11 or higher (Required) - ContextDigger is a Python CLI tool
    Check: python3 --version
  • ✓
    Terminal/Command Line (Required) - Run contextdigger commands
    Any terminal works: bash, zsh, PowerShell, etc.
  • ○
    AI Assistant Integration (Optional) - e.g. Claude, ChatGPT, Gemini, Copilot, Cursor
    Get it at: claude.com/claude-code
    Adds /dig-* commands for AI workflows
  • ○
    Git (Optional but recommended) - For team collaboration and history tracking
    Check: git --version

⚡ Step 0.2: Quick Install (Recommended)

Install ContextDigger with a single command:

$ pip install contextdigger

✅ What this does:

  • • Checks Python version (requires 3.11+)
  • • Installs the ContextDigger Python package
  • • Installs all 43 chat/IDE skills (for tools like Claude)
  • • Works for both fresh installs and upgrades

⏱️ This takes 30-60 seconds

You'll see progress messages as it installs the package and skills.

✅ Step 0.3: Verify Installation

Make sure everything installed correctly:

Check the Python package:

$ contextdigger --version
ContextDigger v1.3.0

Check the installed chat/IDE skills (e.g. for Claude):

$ ls ~/.claude/commands/*dig*.md | wc -l
43

You should see 43 skill files installed.

🔧 Troubleshooting Common Issues

❌ "contextdigger: command not found"

The pip user bin directory isn't in your PATH.

# Add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
# Then reload:
source ~/.bashrc

❌ "Python 3.11+ required"

Upgrade Python to version 3.11 or higher.

Visit: python.org/downloads

📋 Alternative: Manual Installation (Click to expand)

Step 1: Install Python Package

$ pip3 install --user contextdigger

Step 2: Install Claude Skills

$ contextdigger install-skills

Step 3: Verify as shown above

✅ Lesson 0 Complete!

ContextDigger is installed and ready to use! Let's initialize your first project.

1

Project Initialization & First Dig

Goal: Initialize ContextDigger in your project and explore your first area

📁 Step 1.1: Navigate to Your Project

Open your terminal and navigate to your project directory:

$ cd ~/projects/my-ecommerce-app

🚀 Step 1.2: Initialize ContextDigger

Initialize ContextDigger using either method:

Method 1: CLI
$ contextdigger init

Direct CLI command

Method 2: Chat/IDE Integration
$ /init-dig

In your AI chat (Claude, ChatGPT, etc.)

✅ Instant Execution

Both methods run instantly with no approval prompts! ContextDigger uses a CLI-based architecture for seamless execution.

What happens:

  • • Scans your entire project
  • • Detects programming languages
  • • Discovers logical code areas (frontend, backend, tests, etc.)
  • • Creates `.cdg/` directory

👁️ Step 1.3: View Your Project Dashboard

CLI
$ contextdigger dashboard
Chat/IDE Skills (e.g. Claude)
$ /dig-dashboard

You'll see:

📊 Project Overview: my-ecommerce-app
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Discovered Areas:
• frontend (React components, 45 files)
• backend-api (Express routes, 23 files)
• database (Models & migrations, 15 files)
• authentication (Auth logic, 8 files)
• tests (Unit & integration, 67 files)

🎯 Step 1.4: Dig Into Your First Area

Let's explore the backend-api area:

CLI
$ contextdigger dig backend-api
Chat/IDE Skills (e.g. Claude)
$ /dig backend-api

What you learn:

  • ✓ All files in this area
  • ✓ Recent changes and who made them
  • ✓ Related areas (what depends on this)
  • ✓ Suggested next steps

✅ Lesson 1 Complete!

You now know how to initialize ContextDigger and navigate to code areas. Time to level up!

2

Navigation & Bookmarks

Goal: Master navigation and bookmark important locations

💡 CLI vs Chat/IDE Commands

ContextDigger provides two interfaces. All commands work the same way:

CLI Commands
$ contextdigger mark-spot [name]
$ contextdigger list-spots
$ contextdigger goto-spot [name]
Chat/IDE Skills (e.g. Claude)
$ /mark-spot [name]
$ /list-spots
$ /goto-spot [name]

For brevity, this lesson shows chat/IDE skill commands (e.g. for Claude). You can always run the equivalent CLI commands by prefixing with contextdigger.

🔖 Bookmark Critical Files

You're in the authentication area and found the login handler. Let's bookmark it:

$ /dig authentication
# Found src/auth/loginHandler.js - this is important!
$ /mark-spot login-handler

💡 Pro Tip:

Use descriptive names like "login-handler", "payment-bug", "api-endpoint" so you remember what they're for.

📍 List All Your Bookmarks

$ /list-spots
Your Bookmarks:
• login-handler → authentication/loginHandler.js
• payment-flow → backend-api/payments/
• checkout-bug → frontend/components/Checkout.jsx

⚡ Jump to Bookmarks Instantly

Now you're working on something else, but need to go back to the login handler:

$ /goto-spot login-handler

Instantly transported to that location, with full context!

🔍 Search Across Everything

Can't remember where the shopping cart code is?

$ /dig-search "shopping cart"

Searches across:

  • • Code area names
  • • File names and paths
  • • Your notes and bookmarks
  • • Navigation history

◀️ ▶️ Browser-Like Navigation

Just like a web browser, you can go back and forward:

# You went: frontend → backend-api → database
$ /dig-back
# Now at: backend-api
$ /dig-back
# Now at: frontend
$ /dig-forward
# Back to: backend-api

✅ Lesson 2 Complete!

You can now navigate like a pro and never lose your place in the codebase!

3

🆕 Multi-Strategy Sub-Area Creation (v1.3.0)

Goal: Transform attention budget constraints into focused workflows with multi-strategy splitting

🎯 The Scenario

You're working on a Salesforce project with 176 Apex test files. You try to dig into them, but hit an attention budget limit. In v1.3.0, this constraint becomes an opportunity for structured, guided workflow!

💡 Dual Interface Reminder

Commands shown work in both CLI (contextdigger split) and chat/IDE skills (/dig-split in Claude, for example).

⚠️ Step 3.1: Hit a Budget Limit (And Don't Panic!)

You discover a large test area and try to dig into it:

$ /dig salesforce-apex-tests
❌ ERROR: Area too large (176 files > 15 files budget)

💡 What's Different in v1.3.0:

Instead of just stopping here, ContextDigger now automatically analyzes those 176 files with 4 intelligent strategies and presents you with focused sub-area suggestions!

🤖 Step 3.2: Interactive Guided Workflow

Instead of an error, you get an interactive menu:

📊 Sub-Area Analysis: 4 suggestions found
┌─ apex-account-tests (23 files) ✓
│ Strategy: naming | Confidence: 95%
│ Pattern: **/*Account*Test.cls
├─ 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)
4. Override budget (dangerous)
5. Exit

🧠 The 4 Strategies (NO AI):

  • • Directory: Groups by parent directory
  • • Naming: Finds common CamelCase/snake_case components
  • • Role: Groups by file role (test, model, controller, etc.)
  • • Imports: Clusters by import relationships

All using regex/pattern matching - zero LLM calls, zero tokens!

✨ Step 3.3: Select and Instantly Create

Choose option 1 and select a sub-area:

Your choice: 1
→ Selected: apex-account-tests
✓ Created sub-area: apex-account-tests
✓ Now digging: apex-account-tests (23 files, 487 lines)
Budget: 23/15 files... wait, that's over!
Just kidding - checking actual file count...
Budget: 23/15 files, 487/3,000 lines (16%)

⚡ Result: 30 Second Transformation!

  • ✓ From budget error to focused exploration
  • ✓ No manual pattern writing
  • ✓ Intelligent grouping based on file analysis
  • ✓ Perfect sub-area created automatically

🎛️ Step 3.4: Explore with Verbosity Levels

Want more detail before selecting? Use verbosity flags:

Option 2: Horizontal Verbose (-v)

Shows file previews, patterns, metadata, and file intelligence:

apex-account-tests (23 files) ✓
Strategy: naming | Confidence: 95%
Pattern: **/*Account*Test.cls
Sample files (5):
AccountTriggerTest.cls (42 lines)
Purpose: Test account trigger logic
Role: test | Imports: Account, Test
Option 3: Vertical Tree (-vv)

Shows hierarchical tree with recursive splits:

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) ✓

See nested splits up to depth 2 - perfect for understanding complex hierarchies!

🔧 Step 3.5: Proactive Manual Split

Want to split an area before hitting budget? Use manual split:

$ /dig-split salesforce-apex-tests -vv
📊 Analyzing 176 files with 4 strategies...
📋 Found 7 potential sub-areas:
[x] apex-account-tests (23 files) ✓
[ ] apex-opportunity-tests (34 files) ⚠️
[x] apex-lead-tests (19 files) ✓
[x] apex-contact-tests (15 files) ✓
(Space to select, Enter to confirm)
✓ Created 3 sub-areas

💡 Pro Tip:

Use -vv to see the hierarchical tree before creating!

⚡ Step 3.6: Quick Create with Exact Pattern

Know exactly what you want? Create directly with a pattern:

$ /create-subarea apex-tests lead "**/*Lead*Test.cls"
🔍 Matching pattern against 176 parent files...
✓ Found 19 matching files
✓ Created sub-area: apex-tests-lead
Files: 19
Lines: 412

⚡ Perfect When You Know the Pattern!

This is the fastest method if you already know the glob pattern you need.

📚 Lesson 3 Summary: Three Ways to Create Sub-Areas

1. Auto-Suggest

Hit budget → Interactive workflow

/dig large-area
2. Manual Split

Proactive split with multi-select

/dig-split area -vv
3. Quick Create

Exact pattern-based creation

/create-subarea

✅ Lesson 3 Complete!

You've mastered v1.3.0's multi-strategy sub-area creation! Context aperture constraints are now opportunities for focused workflows.

4

Code Intelligence

Goal: Understand code relationships and impact

💡 Dual Interface Reminder

Commands shown work in both CLI (contextdigger deps) and chat/IDE skills (/dig-deps in Claude, for example).

🔗 View Dependencies

Before changing the authentication system, see what depends on it:

$ /dig-deps authentication
Dependencies of authentication:
→ backend-api (imports auth middleware)
→ frontend (uses auth tokens)
→ database (user model)
→ tests (authentication tests)
⚠️ 4 areas depend on authentication

💥 Impact Analysis

Planning to refactor the database layer? See the blast radius:

$ /dig-impact database

⚠️ Impact Report:

  • Direct impact: 23 files import from database/
  • Indirect impact: 67 files will be affected
  • Tests to update: 34 test files
  • Risk level: HIGH - this is core infrastructure

🔥 Find Hotspots

Which files change most frequently? These might need refactoring:

$ /dig-hotspots
Most Changed Files (last 30 days):
🔥🔥🔥 api/products.js (47 commits)
🔥🔥 components/Cart.jsx (31 commits)
🔥🔥 database/migrations/ (28 commits)
🔥 auth/loginHandler.js (19 commits)

✅ Check Test Coverage

$ /dig-coverage backend-api

Coverage Report:

Overall: 78%
⚠️ api/payments.js: 45% (needs more tests!)
✓ api/products.js: 95%
✓ api/users.js: 89%

✅ Lesson 4 Complete!

You can now analyze dependencies, impact, and make informed decisions before changing code!

5

Context Snapshots

Goal: Save and restore your work context

💡 Dual Interface Reminder

Commands shown work in both CLI (contextdigger snapshot) and chat/IDE skills (/dig-snapshot in Claude, for example).

📸 Save Your Current Context

You're deep into a feature. Boss says "drop everything, critical bug!" Save your context first:

# Currently working on: new checkout flow
$ /dig-snapshot checkout-feature
# Saved: current area, bookmarks, history, notes

🐛 Handle the Urgent Bug

$ /dig-search "payment timeout"
$ /dig backend-api
# Fix the bug...
$ /dig-note "Fixed payment timeout in stripe integration"

🔄 Restore Your Context

Bug fixed! Now get back to exactly where you were:

$ /dig-load checkout-feature

Restored:

  • ✓ Back in frontend/checkout area
  • ✓ All your bookmarks loaded
  • ✓ History restored
  • ✓ Notes available

📝 View Your History

$ /dig-history
Your Navigation History:
2:45pm → frontend/checkout (snapshot: checkout-feature)
2:30pm → backend-api/payments (fixed bug)
2:15pm → frontend/checkout
1:50pm → backend-api
1:30pm → authentication

✅ Lesson 5 Complete!

You can now handle interruptions without losing your place. Context switching is painless!

6

Team Collaboration

Goal: Share knowledge and collaborate with your team

💡 Dual Interface Reminder

Commands shown work in both CLI (contextdigger note) and chat/IDE skills (/dig-note in Claude, for example).

📝 Document Your Discoveries

Found something important? Share it with your team:

$ /dig authentication
$ /dig-note "JWT tokens expire after 24h. Refresh token endpoint: /api/auth/refresh"

📚 Generate Team Wiki

$ /dig-wiki

Auto-generates a searchable wiki from all team notes. Perfect for onboarding!

👥 See What Teammates Are Doing

$ /dig-team
Team Activity:
👤 Sarah → frontend/components (working on new UI)
👤 Marcus → backend-api/payments (refactoring)
👤 You → authentication

🎯 Find Code Owners

Who knows the payment system best?

$ /dig-who payments

Experts for payments:

  • 1. Marcus (67% of commits)
  • 2. Elena (28% of commits)
  • 3. Jordan (5% of commits)

✅ Lesson 5 Complete!

You're now collaborating effectively and preserving team knowledge!

🎉

Tutorial Complete!

You've mastered the core ContextDigger workflows

✅

Navigation

Move through codebases with precision

✅

Intelligence

Understand dependencies & impact

✅

Collaboration

Share knowledge with your team

Explore All Commands See Real Use Cases