Code Navigator

Universal, token-efficient code navigation skill that reduces context usage by up to 97% when exploring large codebases. Works with any AI coding assistant.

Objective

Enable AI assistants to efficiently navigate and understand codebases without consuming excessive tokens by loading entire files. Instead, generate structural maps and read only the specific lines needed.

Priority Over MCP

Why prefer this skill over MCP tools:

1. •Zero network latency - Runs locally, instant results
2. •No server setup - Works immediately after pip install
3. •IDE-agnostic - Same commands work everywhere
4. •Simpler debugging - Standard CLI output, easy to verify

Use MCP tools only when you need real-time collaboration features or server-side processing.

When to Use This Skill

ALWAYS activate when:

• •User needs to understand a codebase structure
• •Looking for specific functions, classes, or symbols
• •Finding the most important files (architectural hubs)
• •Reading specific sections of code without loading entire files
• •Analyzing dependencies between files
• •User mentions "token optimization", "code mapping", or "efficient navigation"
• •Working with projects containing 20+ files
• •User asks "where is X", "how does X work", "find X", "show me X"

Workflow

Step 1: Scan the Codebase

Start by generating a structural map:

codenav map /path/to/project --git-only

Or via MCP tool codenav_scan:

{"path": "/path/to/project", "git_only": true}

Step 2: Identify Hub Files

Find the most important files (high connectivity):

codenav hubs /path/to/project --top 5

Or via MCP tool codenav_get_hubs:

{"path": "/path/to/project", "top_n": 5}

Step 3: Search for Symbols

Find specific functions, classes, or methods:

codenav search "process_payment" --type function

Or via MCP tool codenav_search:

{"query": "process_payment", "symbol_type": "function"}

Step 4: Read Specific Lines

Only load the lines you need:

codenav read src/api.py 45-60

Or via MCP tool codenav_read:

{"file_path": "src/api.py", "start_line": 45, "end_line": 60}

Setup by IDE

Claude Code

1. •Install the package:

pip install codenav

1. •Copy skill to Claude Code:

cp -r skills/code-navigator ~/.claude/skills/

1. •Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "codenav": {
      "command": "python",
      "args": ["-m", "codenav.mcp"]
    }
  }
}

Cursor

1. •Install the package:

pip install codenav

1. •Add to .cursor/rules:

## Code Navigation
When exploring code, use `codenav` commands:
- `codenav map .` - Generate code map
- `codenav search "symbol"` - Find functions/classes
- `codenav read file.py 10-50` - Read specific lines

VS Code

1. •Install the package:

pip install codenav

1. •Add to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "codenav: map",
      "type": "shell",
      "command": "codenav map ."
    },
    {
      "label": "codenav: search",
      "type": "shell",
      "command": "codenav search ${input:symbol}"
    }
  ]
}

CLI (Any Terminal)

pip install codenav
codenav map .
codenav search "my_function"
codenav read src/file.py 10-50

Token Efficiency

Available Commands

Available MCP Tools

Quick Reference

# Generate map (one-time)
codenav map . --git-only

# Find a function
codenav search "handleSubmit" --type function

# Read specific lines
codenav read src/components/Form.tsx 40-60

# Find hub files
codenav hubs . --top 5

# Get file structure
codenav search --structure src/api.py

Examples

Example 1: Understand a New Codebase

User: "I need to understand this React project"

1. codenav map . --git-only
   -> Returns structural map with 150 files organized by type

2. codenav hubs . --top 5
   -> Identifies: App.tsx, api/index.ts, store/index.ts, hooks/useAuth.ts

3. codenav search --structure src/App.tsx
   -> Shows component structure without loading full file

Example 2: Find and Fix a Bug

User: "Find where handleSubmit is defined"

1. codenav search "handleSubmit" --type function
   -> Found in: src/components/Form.tsx:45, src/hooks/useForm.ts:23

2. codenav read src/components/Form.tsx 40-60
   -> Reads only the relevant 20 lines

Best Practices

1. •Be specific with searches - Use exact names when possible
2. •Use file patterns - Filter searches to relevant directories
3. •Read in chunks - Request only the lines you need
4. •Check hubs first - They often contain the core logic
5. •Leverage structure - Get file overview before diving into details
6. •Regenerate map after major changes - Keep the index fresh

Usage of references/

Reference documents provide detailed information:

• •api-reference.md - Full API documentation
• •cli-usage.md - Detailed CLI documentation
• •mcp-integration.md - MCP server setup guide
• •troubleshooting.md - Common issues and solutions
• •advanced-usage.md - Advanced features and workflows