---
name: csp-search
description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over bash/read_file for any semantic or exploratory question.
runAs: subagent
allowed-tools: bash, read_file
---
Use `csp search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
```bash
csp search "authentication flow" ./my-project
csp search "save_pretrained" ./my-project
csp search "save model to disk" ./my-project --top-k 10
```
If you anticipate doing more than one search, use `csp index` to create an index.
```bash
csp index ./my-project -o my_index
```
You can then reuse this index later on:
```bash
csp search "save_pretrained" --index my_index
```
An index is not automatically updated, so if the code changes significantly, reindex. If you notice stale results while resolving searches to files, reindex.
Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
```bash
csp search "deployment guide" ./my-project --content docs
csp search "database host port" ./my-project --content config
csp search "authentication" ./my-project --content all
```
Use `csp find-related` to discover code similar to a known location (pass `filePath` and `line` from a prior search result):
```bash
csp find-related src/auth.ts 42 ./my-project
```
Like search, `find-related` also accepts an `--index` argument.
`path` defaults to the current directory when omitted; git URLs are accepted.
If `csp` is not on `$PATH`, use `bunx @pleaseai/csp` in its place.
### Workflow
1. Index the repo using `csp index -o cached_index`.
2. Start with `csp search` to find relevant chunks. Pass the index to achieve results faster.
3. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
4. Inspect full files only when the returned chunk does not give enough context.
5. Optionally use `csp find-related` with a promising result's `filePath` and `line` to discover related implementations.
6. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.