sanurb/index-codebase

Index Codebase

Set up local indexes that give agents fast, token-efficient code understanding. Two complementary tools:

• codemogger — semantic + keyword search ("find code related to authentication")
• cx — symbol navigation: overview, definition, references ("show me function X")

Together they cover discovery (find relevant code) and navigation (inspect specific symbols). Neither requires Docker, API keys, or running servers.

When to Use Which

What does the agent need?
├─ "Find code related to <concept>"     → codemogger (semantic search)
├─ "What symbols are in this file?"     → cx overview
├─ "Show me function X"                 → cx definition
├─ "Where is X used?"                   → cx references
├─ "Find all files matching <pattern>"  → ripgrep (not this skill)
└─ "Understand full file context"       → Read tool (not this skill)

Use codemogger when the agent doesn't know symbol names yet — exploring an unfamiliar codebase, searching by concept, or finding code by natural language description.

Use cx when the agent knows a target — getting a file overview before reading, extracting a function body before editing, or tracing references before refactoring.

Use both for architecture analysis: codemogger discovers relevant modules → cx navigates their internals.

Instructions

Step 1. Check what's already indexed

# codemogger — check for existing database
ls .codemogger/ 2>/dev/null && echo "codemogger: indexed" || echo "codemogger: not indexed"

# cx — check for existing index
ls .cx-index.db 2>/dev/null && echo "cx: indexed" || echo "cx: not indexed"

If both exist and files haven't changed significantly, skip to Step 4 (verify). If files changed since last codemogger index, run npx codemogger reindex instead of full index. cx updates automatically on invocation (mtime-based).

Step 2. Install and index with cx

cx is a Rust binary. Install once:

# Check if installed
cx --version 2>/dev/null || cargo install cx-cli

Install language grammars for the project's languages. cx auto-detects what's needed:

cx overview src/main.rs 2>&1 || true
# If cx reports missing grammars, it prints the exact install command:
# cx lang add rust typescript python  (adjust to project languages)

First invocation builds .cx-index.db automatically. Add to .gitignore:

grep -q '.cx-index.db' .gitignore 2>/dev/null || echo '.cx-index.db' >> .gitignore

Step 3. Install and index with codemogger

npx codemogger index .

This parses all source files with tree-sitter, chunks them into semantic units, embeds them with a local model (~22MB, no API key), and stores everything in .codemogger/. First run on a large codebase takes minutes; incremental updates are fast.

Add to .gitignore:

grep -q '.codemogger' .gitignore 2>/dev/null || echo '.codemogger/' >> .gitignore

Step 4. Verify

Run test queries to confirm both indexes work:

# cx: file overview (should list symbols with signatures)
cx overview "$(find . -name '*.rs' -o -name '*.ts' -o -name '*.py' | head -1)"

# cx: project-wide symbol search
cx symbols --kind fn | head -10

# codemogger: semantic search
npx codemogger search "main entry point"

Each must return at least 1 result. If cx reports missing grammars, install them with cx lang add <language>.

Step 5 (Optional). Zoekt for trigram regex search

For very large codebases (>10k files) where complex regex patterns are needed:

# Install if missing
which zoekt-index || go install github.com/sourcegraph/zoekt/cmd/...@latest

# Index
zoekt-git-index -index ~/.zoekt .

Agent Workflow After Indexing

The indexed codebase enables this escalation hierarchy — start cheap, escalate only when needed:

| Step | Tool | Token cost | When | |------|------|-----------|------| | Discover | npx codemogger search "concept" | ~500 tokens | Don't know what to look for | | Overview | cx overview <file> | ~200 tokens | Know the file, want structure | | Navigate | cx definition --name <symbol> | ~200 tokens | Know the symbol, want body | | Trace | cx references --name <symbol> | ~100–500 tokens | Need impact analysis | | Deep read | Read tool | ~1,200 tokens | Need full file context |

Instruct agents via cx's built-in skill file:

# For Claude Code
cx skill > ~/.claude/CX.md
# Add @CX.md to ~/.claude/CLAUDE.md

# For AGENTS.md-compatible tools
cx skill >> AGENTS.md

Non-Negotiables

• At minimum one index must exist after completion (cx or codemogger).
• Both .cx-index.db and .codemogger/ must be in .gitignore.
• A test query on each installed tool must return at least 1 result.
• Do NOT modify any source files during indexing.

Output

Index complete.
- cx: <N> files indexed in .cx-index.db (languages: rust, typescript, ...)
- codemogger: <N> files indexed in .codemogger/
- zoekt: indexed at ~/.zoekt/ (if applicable)
- .gitignore: updated
- Agent skill file: cx skill injected into AGENTS.md (if applicable)

Troubleshooting

| Problem | Fix | |---------|-----| | cx: no language grammars installed | Run cx lang add <languages> — cx tells you which | | cx: database locked | Another cx process is writing. Wait 2s or rm .cx-index.db | | codemogger returns 0 results | Run npx codemogger reindex . | | cx not found | cargo install cx-cli (requires Rust toolchain) | | codemogger slow on first run | Normal — embedding is ~97% of time. Subsequent runs are incremental | | Monorepo indexes too much | Use --root with cx or scope codemogger to a subdirectory |

In This Reference

| Tool | What it does | Query style | |------|-------------|-------------| | cx | Symbol index + byte-range extraction | Exact: name, kind, file filters | | codemogger | AST-chunked embeddings + dual search | Fuzzy: natural language + keywords | | zoekt | Trigram regex index | Regex patterns across all files | | ripgrep | Line-level text search | Exact text/regex (no indexing) |