# 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** (built-in file/shell tools disabled), the agent has no
choice but to use Catenary's LSP tools — no system prompt changes are needed.
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 where something is defined | `definition` | grep/ripgrep |
| Find all usages of a symbol | `find_references` | grep/ripgrep |
| Get type info or documentation | `hover` | Reading entire files |
| Understand a file's structure | `document_symbols` | Reading entire files |
| Find a class/function by name | `search` | grep/glob patterns |
| See available methods on an object | `completion` | Reading class definitions |
| Find implementations of interface | `implementation` | grep for impl blocks |
| Rename a symbol safely | `rename` | Find/replace with grep |
| Check for errors after edits | `diagnostics` | Running compiler |
| Explore unfamiliar codebase | `codebase_map` | Multiple grep/read cycles |
### Why This Matters
- A single 500-line file read costs ~2000-4000 tokens
- An `hover` call costs ~50-200 tokens
- 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 File I/O
Catenary provides both LSP tools and file I/O tools (`read_file`, `write_file`,
`edit_file`, `list_directory`). Use LSP tools for navigation and understanding;
use file I/O for reading implementation logic and making changes.
**Use LSP tools** for:
- Finding definitions, references, and symbols
- Getting type info and documentation (hover)
- Understanding file structure (document_symbols)
- Checking errors after changes (diagnostics)
**Use file I/O tools** for:
- Reading implementation logic (not just signatures)
- Searching comments or string literals (`search` includes a file heatmap)
- Config files or non-code content
- Writing and editing code (`write_file`, `edit_file` return diagnostics
automatically)
## 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. `search` for "auth" - returns symbol names with locations
2. `definition` to jump to the specific handler
3. `hover` on unfamiliar types to understand them
4. `find_references` to see how the handler is called
5. `read_file` on the specific function you need to modify
6. `edit_file` to make the change — diagnostics returned automatically
## Codebase Orientation
When first exploring an unfamiliar codebase:
```
# Get project structure with function/class names
codebase_map with include_symbols: true
# Then drill down with targeted queries
search for specific components
document_symbols for file structure
# Read implementation when needed
read_file for 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 |
| `hover` response | ~50-200 |
| `definition` response | ~30-100 |
| `find_references` (10 results) | ~200-500 |
| `document_symbols` | ~200-800 |
| `codebase_map` (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 `document_symbols` or `codebase_map` to
understand organization before reading implementation.
3. **Hover before read.** Check `hover` for type signatures and docs before
reading source files.
4. **References are precise.** `find_references` finds actual usages,
not text matches. No false positives from comments or strings.
5. **Save reads for logic.** Only use `read_file` when you need to understand
_how_ something works, not _what_ it is or _where_ it lives.
6. **Edit with feedback.** Use `edit_file` and `write_file` — they return LSP
diagnostics automatically, so you immediately see any errors introduced.
## Display Hooks
Catenary's `edit_file` and `write_file` tools pass raw JSON parameters to the
CLI, which can be hard to review. The bundled hook script formats these as
colorized diffs and previews.
### Claude Code
Copy the script and make it executable:
```bash
mkdir -p ~/.claude/hooks
cp .claude-plugin/plugins/catenary/hooks/format_tool_output.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/format_tool_output.py
```
Add to `~/.claude/settings.json` (all projects) or `.claude/settings.json`
(single project):
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__.*__edit_file|mcp__.*__write_file",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/format_tool_output.py"
}
]
}
]
}
}
```
### Gemini CLI
Not currently supported. Gemini CLI's `BeforeTool` hook fires *after* the user
approves the tool call, so there's no way to show a formatted diff in the
approval prompt. The hook output only appears in the debug console, not the
main UI.
### What you get
- **edit_file**: colorized unified diff (red = removed, green = added)
- **write_file**: file header with line count and first 30 lines numbered