AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->
3 
4# tools
5 
6IDE-like capabilities for AI agents via Language Server Protocol (LSP), Abstract Syntax Tree (AST) tools, and Python REPL.
7 
8## Purpose
9 
10This directory provides agents with powerful code intelligence tools:
11- **LSP Tools (12)**: Hover info, go-to-definition, find references, diagnostics, rename, code actions
12- **AST Tools (2)**: Structural code search and transformation via ast-grep
13- **Python REPL (1)**: Interactive Python execution for data analysis
14 
15These tools enable agents to understand and manipulate code at a semantic level, far beyond text search.
16 
17## Key Files
18 
19| File | Description |
20|------|-------------|
21| `index.ts` | Tool registry - exports `allCustomTools`, `lspTools`, `astTools` |
22| `lsp-tools.ts` | 12 LSP tool definitions (hover, definition, references, etc.) |
23| `ast-tools.ts` | 2 AST tools for pattern search and replace |
24 
25## Subdirectories
26 
27| Directory | Purpose |
28|-----------|---------|
29| `lsp/` | LSP client, server configs, utilities (see `lsp/AGENTS.md`) |
30| `diagnostics/` | Directory-level diagnostics (tsc/LSP) (see `diagnostics/AGENTS.md`) |
31| `python-repl/` | Python REPL tool for data analysis |
32 
33## For AI Agents
34 
35### Working In This Directory
36 
37#### LSP Tools Usage
38 
39**Basic code intelligence:**
40```typescript
41// Get type info at position
42lsp_hover({ file: "src/index.ts", line: 10, character: 15 })
43 
44// Jump to definition
45lsp_goto_definition({ file: "src/index.ts", line: 10, character: 15 })
46 
47// Find all usages
48lsp_find_references({ file: "src/index.ts", line: 10, character: 15 })
49```
50 
51**File/project analysis:**
52```typescript
53// Get file outline (all symbols)
54lsp_document_symbols({ file: "src/index.ts" })
55 
56// Search symbols across workspace
57lsp_workspace_symbols({ query: "createSession", file: "src/index.ts" })
58 
59// Single file diagnostics
60lsp_diagnostics({ file: "src/index.ts", severity: "error" })
61 
62// PROJECT-WIDE type checking (RECOMMENDED)
63lsp_diagnostics_directory({ directory: ".", strategy: "auto" })
64```
65 
66**Refactoring support:**
67```typescript
68// Check if rename is valid
69lsp_prepare_rename({ file: "src/index.ts", line: 10, character: 15 })
70 
71// Preview rename (does NOT apply changes)
72lsp_rename({ file: "src/index.ts", line: 10, character: 15, newName: "newFunction" })
73 
74// Get available code actions
75lsp_code_actions({ file: "src/index.ts", startLine: 10, startCharacter: 0, endLine: 10, endCharacter: 50 })
76```
77 
78#### AST Tools Usage
79 
80**Pattern search with meta-variables:**
81```typescript
82// Find all function declarations
83ast_grep_search({ pattern: "function $NAME($$$ARGS)", language: "typescript", path: "src" })
84 
85// Find console.log calls
86ast_grep_search({ pattern: "console.log($MSG)", language: "typescript" })
87 
88// Find if statements
89ast_grep_search({ pattern: "if ($COND) { $$$BODY }", language: "typescript" })
90 
91// Find null checks
92ast_grep_search({ pattern: "$X === null", language: "typescript" })
93```
94 
95**AST-aware replacement:**
96```typescript
97// Convert console.log to logger (dry run by default)
98ast_grep_replace({
99  pattern: "console.log($MSG)",
100  replacement: "logger.info($MSG)",
101  language: "typescript",
102  dryRun: true  // Preview only
103})
104 
105// Convert var to const
106ast_grep_replace({
107  pattern: "var $NAME = $VALUE",
108  replacement: "const $NAME = $VALUE",
109  language: "typescript",
110  dryRun: false  // Apply changes
111})
112```
113 
114**Meta-variable syntax:**
115- `$NAME` - Matches any single AST node (identifier, expression, etc.)
116- `$$$ARGS` - Matches multiple nodes (function arguments, list items, etc.)
117 
118#### Diagnostics Strategy
119 
120The `lsp_diagnostics_directory` tool supports two strategies:
121 
122| Strategy | When Used | Speed | Accuracy |
123|----------|-----------|-------|----------|
124| `tsc` | tsconfig.json exists | Fast | High (full type checking) |
125| `lsp` | No tsconfig.json | Slow | File-by-file |
126| `auto` | Default | Varies | Picks best available |
127 
128**Recommendation**: Use `strategy: "auto"` (default) - it prefers `tsc` when available.
129 
130### Modification Checklist
131 
132#### When Adding a New Tool
133 
1341. Define tool in appropriate file (`lsp-tools.ts`, `ast-tools.ts`, or new file)
1352. Export from `index.ts` (add to `allCustomTools`)
1363. Update `src/mcp/omc-tools-server.ts` if exposed via MCP
1374. Update `docs/REFERENCE.md` (MCP Tools section)
1385. Update agent tool assignments in `src/agents/definitions.ts` if needed
1396. Update `docs/CLAUDE.md` (Agent Tool Matrix) if assigned to agents
140 
141### Testing Requirements
142 
143```bash
144# Test LSP tools (requires language server installed)
145npm test -- --grep &quot;lsp&quot;
146 
147# Test AST tools
148npm test -- --grep &quot;ast&quot;
149```
150 
151### Common Patterns
152 
153**Tool Definition Structure:**
154```typescript
155export const myTool: ToolDefinition<{
156  param: z.ZodString;
157}> = {
158  name: 'tool_name',
159  description: 'What this tool does',
160  schema: {
161    param: z.string().describe('Parameter description')
162  },
163  handler: async (args) => {
164    // Implementation
165    return { content: [{ type: 'text', text: 'result' }] };
166  }
167};
168```
169 
170**Error handling:**
171```typescript
172async function withLspClient(filePath, operation, fn) {
173  try {
174    const client = await lspClientManager.getClientForFile(filePath);
175    if (!client) {
176      // Return helpful installation hints
177    }
178    return fn(client);
179  } catch (error) {
180    return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
181  }
182}
183```
184 
185## Dependencies
186 
187### Internal
188- `lsp/` - LSP client and server configurations
189- `diagnostics/` - Directory diagnostics (tsc/LSP aggregator)
190 
191### External
192| Package | Purpose |
193|---------|---------|
194| `zod` | Runtime schema validation for tool parameters |
195| `@ast-grep/napi` | AST parsing and pattern matching |
196| `vscode-languageserver-protocol` | LSP types |
197 
198## Tool Summary
199 
200### LSP Tools (12)
201 
202| Tool | Purpose |
203|------|---------|
204| `lsp_hover` | Type info/docs at position |
205| `lsp_goto_definition` | Jump to symbol definition |
206| `lsp_find_references` | Find all usages |
207| `lsp_document_symbols` | File outline |
208| `lsp_workspace_symbols` | Cross-workspace symbol search |
209| `lsp_diagnostics` | Single file errors/warnings |
210| `lsp_diagnostics_directory` | **Project-wide type checking** |
211| `lsp_servers` | List available language servers |
212| `lsp_prepare_rename` | Check if rename is valid |
213| `lsp_rename` | Preview multi-file rename |
214| `lsp_code_actions` | Available refactorings/fixes |
215| `lsp_code_action_resolve` | Get action details |
216 
217### AST Tools (2)
218 
219| Tool | Purpose |
220|------|---------|
221| `ast_grep_search` | Structural code search with patterns |
222| `ast_grep_replace` | AST-aware code transformation |
223 
224### Python REPL (1)
225 
226| Tool | Purpose |
227|------|---------|
228| `python_repl` | Execute Python code for data analysis |
229 
230## Language Support
231 
232### LSP (via language servers)
233| Language | Server | Install |
234|----------|--------|---------|
235| TypeScript/JavaScript | typescript-language-server | `npm i -g typescript-language-server typescript` |
236| Python | ty | `Install ty from https://github.com/astral-sh/ty` |
237| Rust | rust-analyzer | `rustup component add rust-analyzer` |
238| Go | gopls | `go install golang.org/x/tools/gopls@latest` |
239| C/C++ | clangd | System package manager |
240| Java | jdtls | Eclipse JDT.LS |
241| JSON | vscode-json-language-server | `npm i -g vscode-langservers-extracted` |
242| HTML | vscode-html-language-server | `npm i -g vscode-langservers-extracted` |
243| CSS | vscode-css-language-server | `npm i -g vscode-langservers-extracted` |
244| YAML | yaml-language-server | `npm i -g yaml-language-server` |
245 
246### AST (via ast-grep)
247JavaScript, TypeScript, TSX, Python, Ruby, Go, Rust, Java, Kotlin, Swift, C, C++, C#, HTML, CSS, JSON, YAML
248 
249<!-- MANUAL: -->
250