---
name: index
description: Index codebase for fast symbol search and navigation
---

# Codebase Indexing Skill

## Description

This skill provides fast symbol search and code navigation across large codebases. It indexes code symbols (functions, classes, variables) and stores them in an optimized SQLite database with full-text search capabilities.

## When to Use

- When you need to quickly find symbols in a large codebase
- When exploring unfamiliar code
- When refactoring and need to find all references
- Before starting work on a new project
- When searching for function definitions or class hierarchies

## Commands

```
/index                       # Index current project
/index --force               # Force reindex all files
/index --status              # Show index statistics
/index --search <query>      # Search for symbols
/index --find <name>         # Find exact symbol definition
/index --refs <name>         # Find all references to a symbol
```

## How to Use

### Step 1: Index the Project

First, index your codebase:

```
/index
```

This will:
- Scan all supported files (.py, .cpp, .h, etc.)
- Parse each file for symbols
- Store symbols in ~/.ieum/index.db
- Skip unchanged files on subsequent runs

### Step 2: Search for Symbols

Search using natural language or exact names:

```
/index --search "user auth"     # Full-text search
/index --find UserService       # Exact name match
/index --find process_data      # Find function
```

### Step 3: Find References

Locate all usages of a symbol:

```
/index --refs calculate_total
```

### Step 4: Explore Hierarchy

Get call or type hierarchies:

```
Get call hierarchy for process_data
Show classes derived from BaseHandler
```

## Indexed Symbol Types

| Type | Description |
|------|-------------|
| `function` | Standalone functions |
| `method` | Class methods |
| `class` | Class definitions |
| `struct` | Struct definitions (C++) |
| `variable` | Module-level variables |
| `constant` | Constants and macros |
| `enum` | Enumeration types |
| `namespace` | Namespaces (C++) |

## Search Syntax

The indexer uses SQLite FTS5 for full-text search:

```
user                    # Simple search
"user service"          # Exact phrase
user OR auth            # Either term
user AND NOT test       # Exclude term
user*                   # Prefix search
```

## Index Storage

- **Location**: `~/.ieum/index.db`
- **Format**: SQLite with FTS5
- **Persistence**: Index survives restarts
- **Updates**: Incremental (only changed files)

## Performance

| Operation | Typical Time |
|-----------|-------------|
| Full index (10K files) | ~30-60 seconds |
| Incremental update | <5 seconds |
| Symbol search | <100ms |
| Reference lookup | <200ms |

## Supported Languages

| Language | File Extensions |
|----------|-----------------|
| Python | .py, .pyi, .pyw |
| C/C++ | .c, .cpp, .cxx, .cc, .h, .hpp |
| JavaScript | .js, .jsx |
| TypeScript | .ts, .tsx |

## Best Practices

1. **Index Early**: Index before starting work on unfamiliar code
2. **Update Regularly**: Run `/index` after pulling new changes
3. **Use Specific Queries**: More specific queries give better results
4. **Check References**: Always check references before renaming

## Examples

### Example 1: Finding a Function

**User Request:** "Where is the login handler defined?"

**Approach:**
1. Search index for "login handler"
2. Show matching functions with file locations
3. Display function signature and docstring

### Example 2: Exploring a Class

**User Request:** "Show me everything about UserManager class"

**Approach:**
1. Find UserManager definition
2. List all methods
3. Find all references across the codebase
4. Show class hierarchy

### Example 3: Pre-Refactoring Check

**User Request:** "How many places use the old_api function?"

**Approach:**
1. Find symbol definition
2. Search for all references
3. Group by file
4. Report total count and locations

## Ignored Paths

The indexer automatically skips:
- `.git`, `.svn`, `.hg`
- `__pycache__`, `.pytest_cache`
- `node_modules`
- `venv`, `.venv`, `env`
- `build`, `dist`, `target`

## Notes

- First indexing takes longer; subsequent runs are incremental
- Index is project-scoped (each project has its own index)
- Syntax errors in files may cause partial indexing
- Binary files are automatically skipped
