---

name: ast-index description: This skill should be used when the user asks to "find a class", "search for symbol", "find usages", "find implementations", "search codebase", "find file", "class hierarchy", "find callers", "module dependencies", "unused dependencies", "find Perl subs", "Perl exports", "find Python class", "Go struct", "Go interface", "find React component", "find TypeScript interface", "find Rust struct", "find Ruby class", "find C# controller", or needs fast code search in Android/Kotlin/Java, iOS/Swift/ObjC, TypeScript/JavaScript, Rust, Ruby, C#, Perl, Python, Go, C++, or Protocol Buffers projects. Also triggered by mentions of "ast-index" CLI tool.

ast-index - Code Search for Multi-Platform Projects

Fast native Rust CLI for structural code search in Android/Kotlin/Java, iOS/Swift/ObjC, TypeScript/JavaScript, Rust, Ruby, C#, Perl, Python, Go, C++, and Proto projects using SQLite + FTS5 index.

Critical Rules

ALWAYS use ast-index FIRST for any code search task. These rules are mandatory:

1. ast-index is the PRIMARY search tool — use it before grep, ripgrep, or Search tool
2. DO NOT duplicate results — if ast-index found usages/implementations, that IS the complete answer
3. DO NOT run grep "for completeness" after ast-index returns results
4. Use grep/Search ONLY when:
   • ast-index returns empty results
   • Searching for regex patterns (ast-index uses literal match)
   • Searching for string literals inside code ("some text")
   • Searching in comments content

Why: ast-index is 17-69x faster than grep (1-10ms vs 200ms-3s) and returns structured, accurate results.

Prerequisites

Install the CLI before use:

Copybrew tap defendend/ast-index
brew install ast-index

Initialize index in project root:

Copycd /path/to/project
ast-index rebuild

The index is stored at ~/.cache/ast-index/<project-hash>/index.db and needs rebuilding when project structure changes significantly.

Supported Projects

Project type is auto-detected by marker files (build.gradle.kts, Package.swift, Makefile.PL, etc.). Python, Go, Proto, WSDL, and C++ files are indexed alongside main project type.

Core Commands

Universal Search

search - Perform universal search across files, symbols, and modules simultaneously.

Copyast-index search "Payment"           # Finds files, classes, functions matching "Payment"
ast-index search "ViewModel"         # Returns files, symbols, modules in ranked order

File Search

file - Find files by name pattern.

Copyast-index file "Fragment.kt"         # Find files ending with Fragment.kt
ast-index file "ViewController"      # Find iOS view controllers

Symbol Search

symbol - Find symbols (classes, interfaces, functions, properties) by name.

Copyast-index symbol "PaymentInteractor" # Find exact symbol
ast-index symbol "Presenter"         # Find all presenters

Class Search

class - Find class, interface, or protocol definitions.

Copyast-index class "BaseFragment"       # Find Android base fragment
ast-index class "UIViewController"   # Find iOS view controller subclass

Usage Search

usages - Find all places where a symbol is used. Critical for refactoring.

Copyast-index usages "PaymentRepository" # Find all usages of repository
ast-index usages "onClick"           # Find all click handler usages

Performance: ~8ms for indexed symbols.

Implementation Search

implementations - Find all classes that extend or implement a given class/interface/protocol.

Copyast-index implementations "BasePresenter"  # Find all presenter implementations
ast-index implementations "Repository"     # Find repository implementations

Class Hierarchy

hierarchy - Display complete class hierarchy tree.

Copyast-index hierarchy "BaseFragment"   # Show fragment inheritance tree

Caller Search

callers - Find all places that call a specific function.

Copyast-index callers "onClick"          # Find all onClick calls
ast-index callers "fetchUser"        # Find API call sites

Call Tree

call-tree - Show complete call hierarchy going UP (who calls the callers).

Copyast-index call-tree "processPayment" --depth 3 --limit 10

File Analysis

imports - List all imports in a specific file.

Copyast-index imports "path/to/File.kt"  # Show Kotlin file imports

outline - Show all symbols defined in a file.

Copyast-index outline "PaymentFragment.kt"    # Show fragment structure

Code Quality

todo - Find TODO/FIXME/HACK comments in code.

Copyast-index todo                           # Find all TODO comments
ast-index todo --limit 10                # Limit results

deprecated - Find @Deprecated annotations.

Copyast-index deprecated                     # Find deprecated items

Git Integration

changed - Show symbols changed in git diff.

Copyast-index changed                        # Changes vs HEAD
ast-index changed --base main            # Changes vs main branch

Public API

api - Show public API of a module.

Copyast-index api "core"                     # Public classes/functions in module

Index Management

Copyast-index init                           # Initialize index for current project

Copyast-index rebuild                    # Full rebuild with dependencies
ast-index rebuild --no-deps          # Skip module dependency indexing
ast-index rebuild --no-ignore        # Include gitignored files
ast-index update                     # Incremental update
ast-index stats                      # Show index statistics

Utility Commands

Copyast-index version                    # Show CLI version
ast-index help                       # Show help message
ast-index help <command>             # Show help for specific command
ast-index install-claude-plugin      # Install Claude Code plugin to ~/.claude/plugins/

Performance Reference

Platform-Specific Commands

Android/Kotlin/Java

Consult: references/android-commands.md

• DI Commands: provides, inject, annotations
• Compose Commands: composables, previews
• Coroutines Commands: suspend, flows
• XML Commands: xml-usages, resource-usages
• Code Quality: deprecated, suppress, todo
• Extensions: extensions
• Navigation: deeplinks

iOS/Swift/ObjC

Consult: references/ios-commands.md

• Storyboard & XIB: storyboard-usages
• Assets: asset-usages
• SwiftUI: swiftui
• Swift Concurrency: async-funcs, main-actor
• Combine: publishers

TypeScript/JavaScript

Consult: references/typescript-commands.md

• Index: class, interface, type, function, const, decorators
• Supports: React (hooks, components), Vue SFC, Svelte, NestJS, Angular
• outline and imports work with TS/JS files

Rust

Consult: references/rust-commands.md

• Index: struct, enum, trait, impl, fn, macro_rules!, mod
• Supports: Derives, attributes (#[test], #[derive])
• outline and imports work with Rust files

Ruby

Consult: references/ruby-commands.md

• Index: class, module, def, Rails DSL
• Supports: RSpec (describe, it, let), Rails (associations, validations)
• outline and imports work with Ruby files

C#/.NET

Consult: references/csharp-commands.md

• Index: class, interface, struct, record, enum, methods, properties
• Supports: ASP.NET attributes, Unity (MonoBehaviour, SerializeField)
• outline and imports work with C# files

Python

Consult: references/python-commands.md

• Index: class, def, async def, decorators
• outline and imports work with Python files

Go

Consult: references/go-commands.md

• Index: package, type struct, type interface, func
• outline and imports work with Go files

Perl

Consult: references/perl-commands.md

• Exports: perl-exports
• Subroutines: perl-subs
• POD: perl-pod
• Imports: perl-imports
• Tests: perl-tests

Module Analysis

Consult: references/module-commands.md

• Module Search: module
• Dependencies: deps, dependents
• Unused Dependencies: unused-deps
• Public API: api

Workflow Recommendations

1. Run ast-index rebuild once in project root to build the index
2. Use ast-index search for quick universal search when exploring
3. Use ast-index class for precise class/interface lookup
4. Use ast-index usages to find all references before refactoring
5. Use ast-index implementations to understand inheritance
6. Use ast-index changed --base main before code review
7. Run ast-index update periodically to keep index fresh

Additional Resources

For detailed platform-specific commands, consult:

• references/android-commands.md - DI, Compose, Coroutines, XML
• references/ios-commands.md - Storyboard, SwiftUI, Combine
• references/typescript-commands.md - React, Vue, Svelte, NestJS, Angular
• references/rust-commands.md - Structs, traits, impl blocks, macros
• references/ruby-commands.md - Rails, RSpec, classes, modules
• references/csharp-commands.md - ASP.NET, Unity, controllers, interfaces
• references/perl-commands.md - Perl exports, subs, POD
• references/python-commands.md - Python classes, functions
• references/go-commands.md - Go structs, interfaces
• references/cpp-commands.md - C/C++ classes, JNI functions
• references/proto-commands.md - Protocol Buffers messages, services
• references/wsdl-commands.md - WSDL services, XSD types
• references/module-commands.md - Module dependencies