# AI Agent Integration
This guide helps AI coding assistants use Catenary effectively. The goal is to
reduce context bloat and token usage by using semantic LSP queries instead of
text-based file scanning.
## System Prompt
In **constrained mode** (text-scanning commands denied via permissions), add
the following to your system prompt or agent instructions to prevent the model
from wasting tokens discovering the deny list through trial and error:
```
Text-scanning shell commands (grep, find, ls, cat, etc.) are denied.
Use Catenary's grep tool for search and glob tool for browsing.
Workarounds will be added to the deny list.
```
If Catenary is running **alongside built-in tools**, agents will default to
what they were trained on (reading files, grepping). Adding the following to
your system prompt nudges them toward LSP queries instead:
```
## Catenary (LSP Tools)
When exploring or navigating code, prefer Catenary's LSP tools over text search:
| Find symbols, references, text matches | `grep` | grep/ripgrep |
| Browse files and directories | `glob` | ls/find/tree |
| Check for errors after edits | hooks | Running compiler |
### Why This Matters
- A single 500-line file read costs ~2000-4000 tokens
- A `grep` call costs ~200-500 tokens and returns symbols + references + text matches
- One file read ≈ 10-20 targeted LSP queries
- Reducing unnecessary reads prevents context compression and re-reads
### When to Still Use Read/Grep
- Understanding implementation logic (not just signatures)
- Searching comments or string literals
- Config files or non-code content
- Small files where full context is needed
```
---
## The Problem
AI agents typically explore codebases by:
1. Running `grep` or similar to find text matches
2. Reading entire files to understand context
3. Repeating this as context windows fill and compress
This creates a "token tax": files are read, forgotten during compression, then
re-read. Each cycle costs tokens and risks hitting rate limits mid-task.
## The Solution
Catenary provides LSP-backed tools that return precise, targeted information.
Instead of reading a 500-line file to find a function's type signature, ask the
language server directly.
## When to Use LSP vs Native File Tools
Catenary provides two MCP tools (`grep` and `glob`) plus post-edit diagnostics
via hooks. File reading and editing is handled by the host tool's native file
operations (e.g. Claude Code's `Read`, `Edit`, `Write`). The `catenary hook post-tool`
hook provides post-edit LSP diagnostics so you immediately see any errors
introduced by changes.
**Use Catenary tools** for:
- Finding symbols, references, and text matches (`grep`)
- Browsing files and directory structure (`glob`)
- Post-edit diagnostics (automatic via hooks)
**Use native file tools** for:
- Reading implementation logic (not just signatures)
- Searching comments or string literals (`grep` includes a file heatmap)
- Config files or non-code content
- Writing and editing code (diagnostics returned via notify hook)
## Workflow Example
**Task:** "Fix the bug in the authentication handler"
**Inefficient approach:**
1. Grep for "auth" - returns 50 matches across 20 files
2. Read 5 files looking for the handler
3. Read 3 more files to understand the types involved
4. Context fills up, compression triggers
5. Re-read files to remember what you learned
**Efficient approach:**
1. `grep` for "auth" — returns symbols, semantic references, and text matches
2. `grep` for the specific handler — definition and type info included in results
3. Read the specific function you need to modify
4. Edit to make the change — diagnostics returned via notify hook
## Codebase Orientation
When first exploring an unfamiliar codebase:
```
# Get project structure with function/class names
glob with pattern: "**" and include_symbols: true
# Then drill down with targeted queries
grep for specific components
# Read implementation when needed
Read the specific code you need to understand
```
This provides a mental map without reading every file.
## Token Efficiency Comparison
Typical token costs (approximate):
| Read a 500-line file | ~2000-4000 |
| `grep` (symbols + references + heatmap) | ~200-500 |
| `glob` (file listing) | ~200-800 |
| `glob` with symbols (budget: 200) | ~800-1000 |
A single file read can cost as much as 10-20 targeted LSP queries.
## Key Principles
1. **Ask, don't scan.** If you have a specific question ("where is X defined?"),
use a targeted LSP query.
2. **Structure before content.** Use `glob` with symbols to understand
organization before reading implementation.
3. **Search before read.** Use `grep` to find symbols, references, and
matches before reading source files.
4. **References are precise.** `grep` enriches results with semantic
references — actual usages, not text matches.
5. **Save reads for logic.** Only read files when you need to understand
_how_ something works, not _what_ it is or _where_ it lives.
6. **Edit with feedback.** The `catenary hook post-tool` hook returns LSP
diagnostics after every edit, so you immediately see any errors introduced.
## Hook Integration
Catenary provides post-edit LSP diagnostics via the `catenary hook post-tool`
command, designed for use as a `PostToolUse` hook in Claude Code.
The recommended setup uses the Catenary plugin (`catenary@catenary`), which
registers the hook automatically. For manual configuration, add to
`.claude/settings.json`:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write|NotebookEdit|Read",
"hooks": [
{
"type": "command",
"command": "catenary hook post-tool --format=claude"
}
]
}
]
}
}
```
The `notify` hook reads the `PostToolUse` JSON from stdin, finds the running
Catenary session for the workspace, and returns LSP diagnostics. It exits
silently on any error so it never blocks the host tool's flow.