ctags-usage

Ctags Usage for Efficient Code Navigation

Overview

This plugin maintains a ctags index at .claude/tags that maps symbol names to their locations. The index includes both definitions and references, making it useful for finding where symbols are defined AND where they are used. Use this index for efficient code navigation with minimal token usage instead of running broad grep or tree searches.

When to Use Ctags

Use ctags lookup FIRST when:

• Finding where a class, function, method, or type is defined
• Finding references to a symbol (where it's used, imported, called)
• Navigating to a symbol's source location
• The user asks "where is X defined?" or "find references to X"

Fall back to grep when:

• Searching for text patterns that aren't symbol names
• Searching for string literals, comments, or documentation
• The ctags lookup returns no results
• Searching in file types not indexed by ctags

How to Query the Tags Index

Direct Tags File Query

Query the tags file using grep for the symbol name:

grep "^SymbolName	" .claude/tags

The tags file format is tab-separated:

symbol_name<TAB>file_path<TAB>pattern_or_line<TAB>kind

Using the Query Script

For cleaner output with file:line format:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/query-tags.sh SymbolName

Returns results like:

src/services/user.ts:42
src/models/user.ts:15

Interpreting Results

• Multiple results indicate the symbol appears in multiple places (definitions AND references)
• Use the kind field to distinguish:
  • c = class, f = function, m = method, v = variable (definitions)
  • r = reference (where the symbol is used/imported/called)
• Filter by kind to narrow results: grep "^Symbol\t" .claude/tags | grep "kind:r" for references only
• Read the specific file at the returned line number

Token Efficiency Strategy

Before (Inefficient)

User: "Where is UserService defined?"

Step 1: grep -r "UserService" .
Result: 50 lines (imports, usages, comments, definition)
Tokens: ~2000

Step 2: Read several files to find the actual definition
Tokens: ~3000 more

Total: ~5000 tokens