README

A code search toolkit for Coqui that provides fast full-text search, symbol lookup, and file discovery powered by ripgrep and universal-ctags.

Requirements

Installing System Dependencies

Debian / Ubuntu:

sudo apt install ripgrep universal-ctags

macOS (Homebrew):

brew install ripgrep universal-ctags

Arch Linux:

sudo pacman -S ripgrep ctags

Installation

composer require coquibot/coqui-toolkit-code-search

Coqui discovers the toolkit automatically via extra.php-agents.toolkits in composer.json. No manual registration needed.

Tools

code_search

Full-text search through file contents using ripgrep. Ideal for finding specific strings, patterns, or code snippets.

symbol_search

Search the symbol index for classes, functions, methods, constants, and other named entities across all indexed languages.

file_structure

Display the symbol outline of a file — classes, methods, functions, properties — organized hierarchically. Useful for understanding file organization before reading it.

search_files

Find files by name pattern. Uses ripgrep's --files mode for fast filesystem traversal.

code_index

Manage the persistent symbol index. Build, update, clear, or check status. Supports multiple search roots.

Index Management

The toolkit maintains a SQLite index at {workspace}/code-search/index.db for fast symbol lookups. The index is built lazily on the first symbol_search or file_structure call.

Index Actions

• build — Full rebuild: scans all files, extracts symbols with ctags, stores in SQLite.
• update — Incremental: only re-indexes files that changed since the last build (based on mtime comparison).
• status — Show index statistics: file count, symbol count, languages, search roots.
• clear — Delete all index data.
• add_root — Add a directory to the search roots for indexing.
• remove_root — Remove a directory from search roots.
• list_roots — Show all configured search roots.

Multi-Root Support

By default, the workspace directory is the only search root. Additional directories can be added:

code_index(action: "add_root", path: "/path/to/project")
code_index(action: "update")

Indexed paths use the format {root}::{relative_path} internally to disambiguate files across roots.

Architecture

src/
├── CodeSearchToolkit.php           # Main toolkit — tools() + guidelines()
├── Contract/
│   ├── ChangeSet.php               # Added/modified/deleted file lists
│   ├── IndexStats.php              # Index statistics value object
│   └── TagEntry.php                # Symbol entry from ctags
├── Exception/
│   ├── BinaryNotFoundException.php # Missing rg/ctags
│   └── IndexException.php         # SQLite/indexing errors
├── Index/
│   ├── CodeIndex.php               # Orchestrates indexing + search
│   └── IncrementalIndexer.php      # Filesystem change detection
├── Runtime/
│   ├── BinaryResolver.php          # Locates rg/ctags binaries
│   ├── CtagsRunner.php             # Runs ctags, parses JSON output
│   ├── ProcessResult.php           # Process execution result VO
│   └── RipgrepRunner.php           # Runs rg, parses JSON output
├── Storage/
│   └── IndexDatabase.php           # SQLite schema + queries
└── Tool/
    ├── CodeIndexTool.php           # code_index tool
    ├── CodeSearchTool.php          # code_search tool
    ├── FileStructureTool.php       # file_structure tool
    ├── SearchFilesTool.php         # search_files tool
    └── SymbolSearchTool.php        # symbol_search tool

Supported Languages

The index recognizes 30+ file extensions including PHP, JavaScript, TypeScript, Python, Ruby, Go, Rust, Java, C/C++, C#, Swift, Kotlin, Scala, Shell, Lua, Perl, R, SQL, CSS/SCSS, HTML, Vue, Svelte, JSON, YAML, TOML, XML, Markdown, GraphQL, and Protobuf.

ctags itself supports 100+ languages — any file type ctags recognizes will have its symbols extracted.

Development

# Install dependencies
composer install

# Run tests
composer test

# Static analysis
vendor/bin/phpstan analyse

License

MIT