Code Intelligence Tools

Relevant source files

• AGENTS.md
• README.ja.md
• README.ko.md
• README.md
• README.zh-cn.md
• assets/oh-my-opencode.schema.json
• src/AGENTS.md
• src/agents/AGENTS.md
• src/cli/AGENTS.md
• src/config/AGENTS.md
• src/config/schema.test.ts
• src/config/schema.ts
• src/features/AGENTS.md
• src/features/claude-tasks/AGENTS.md
• src/hooks/AGENTS.md
• src/hooks/claude-code-hooks/AGENTS.md
• src/hooks/index.ts
• src/index.ts
• src/mcp/AGENTS.md
• src/plugin-handlers/AGENTS.md
• src/shared/AGENTS.md
• src/tools/AGENTS.md

This page documents the code intelligence tools that provide semantic understanding and structural manipulation of codebases. These tools fall into two categories: LSP (Language Server Protocol) tools for semantic code operations, and AST-Grep tools for structural pattern matching and transformation across 25+ programming languages.

For information about other tool categories, see Delegation Tools, Background Task Tools, Session Management Tools, and Specialized Tools.

Overview

Code intelligence tools enable agents to perform advanced code analysis and refactoring operations that go beyond simple text manipulation. Unlike basic file operations, these tools understand code structure, semantics, and relationships:

Tool Category	Count	Primary Use Cases
LSP Tools	6	Symbol navigation, diagnostics, semantic refactoring
AST-Grep Tools	2	Structural search and replace, pattern-based refactoring

Sources: src/tools/AGENTS.md1-109 README.md190-191

LSP Tools

Architecture Overview

The LSP integration provides semantic code intelligence through the Language Server Protocol. The system maintains a singleton LSPServerManager that manages Language Server lifecycles with reference counting for efficient resource usage.

Diagram: LSP Tool Architecture and Server Management

Sources: src/tools/AGENTS.md31-40 src/tools/lsp/client.ts1-596

Available LSP Tools

The system provides 6 core LSP tools for semantic code operations:

Tool Name	Parameters	Purpose
lsp_goto_definition	filePath, line, character	Navigate to symbol definition, cross-file navigation
lsp_find_references	filePath, line, character, includeDeclaration	Find all symbol references across project
lsp_symbols	filePath, scope (document/workspace), query, limit	List document or workspace symbols for discovery
lsp_diagnostics	filePath, severity	Get compilation/lint errors and warnings
lsp_prepare_rename	filePath, line, character	Validate rename operation is safe
lsp_rename	filePath, line, character, newName	Rename symbol across entire project

All LSP tools are implemented as direct ToolDefinition objects rather than factory functions, providing consistent parameter handling and validation.

Sources: src/tools/AGENTS.md42-50

LSP Client Implementation

The LSP client (client.ts) manages the JSON-RPC communication protocol over stdio with language servers:

Diagram: LSP Client Lifecycle and Request Handling

Key implementation details:

• Singleton Management: LSPServerManager is implemented as a singleton with reference counting to efficiently manage language server lifecycles
• JSON-RPC Protocol: Communication follows the Language Server Protocol specification using JSON-RPC message format
• Stdio Communication: Language servers communicate via stdin/stdout using JSON-RPC
• Capability Negotiation: Server capability discovery during initialization ensures only supported operations are called
• Temp Directory Support: Enables LSP analysis of external codebases beyond the primary project directory

Sources: src/tools/AGENTS.md42-50

LSP Tool Usage Patterns

Agents commonly use LSP tools in these workflows:

1. Refactoring Workflow:

   • lsp_prepare_rename → validate rename is safe
   • lsp_rename → perform project-wide rename
   • lsp_diagnostics → verify no errors introduced

2. Code Exploration:

   • lsp_symbols → discover available symbols (document or workspace scope)
   • lsp_goto_definition → navigate to implementation
   • lsp_find_references → understand usage patterns

3. Error Resolution:

   • lsp_diagnostics → identify compilation errors by severity
   • Apply fixes manually or through other tools
   • Re-run diagnostics to verify resolution

Sources: README.md190-191 src/tools/AGENTS.md42-50

AST-Grep Tools

Pattern-Based Code Search

AST-Grep tools provide structural pattern matching across 25+ programming languages using the @ast-grep/napi Rust/C++ binding. Unlike text-based search (grep), AST-Grep understands code structure and can match patterns while ignoring irrelevant formatting differences.

Diagram: AST-Grep Pattern Matching Architecture

Sources: src/tools/AGENTS.md52-60

Available AST-Grep Tools

Tool Name	Purpose	Pattern Syntax
ast_grep_search	Find code patterns structurally	Meta-variables: $VAR (single), $$$ (multi)
ast_grep_replace	Transform code based on patterns	Same pattern syntax + replacement template

Supported Languages: TypeScript, JavaScript, Python, Rust, Go, Java, C/C++, C#, Ruby, PHP, Kotlin, Swift, Dart, Lua, HTML, CSS, and more (25 languages total).

Sources: src/tools/AGENTS.md52-60 README.md191

Pattern Matching Syntax

AST-Grep uses meta-variables to match code patterns:

Meta-variable	Matches	Example Pattern	Matches Code
$VAR	Single AST node	console.log($MSG)	console.log("hello")
$$$	Multiple nodes	function $NAME($$$ARGS)	function foo(a, b, c)
$_	Anonymous match	if ($COND) { $_ }	Any if statement body

Example Search Pattern:

This pattern finds delegate_task calls while capturing the agent and task arguments into variables $AGENT and $TASK, and matches any additional arguments with $$$.

Sources: src/tools/AGENTS.md52-60

AST-Grep Performance

The Rust/C++ implementation provides significant performance advantages:

Diagram: AST-Grep Performance Model

Key performance features:

• Native Speed: Rust/C++ binding via @ast-grep/napi provides near-native performance
• Streaming AST: Does not load entire AST into memory
• Parallel Processing: Multi-threaded file processing
• Language-Specific Parsers: Uses optimized Tree-sitter grammars per language

Sources: src/tools/AGENTS.md52-60

Tool Integration with Agents

Permission Model

Code intelligence tools have different permission requirements across agents:

Agent	LSP Tools	AST-Grep Tools	Rationale
Sisyphus	✓ Allow	✓ Allow	Primary orchestrator needs full access
Oracle	✓ Allow	✓ Allow	Read-only consultation agent
Librarian	✓ Allow	✓ Allow	Documentation research
Explore	✓ Allow	✓ Allow	Fast codebase exploration
Multimodal-Looker	✗ Deny	✗ Deny	Limited to read/glob/grep

Sources: src/agents/AGENTS.md25-35

Tool Execution Flow

Diagram: Code Intelligence Tool Execution with Hooks

Sources: src/hooks/AGENTS.md88-111

File Structure and Implementation

Directory Layout

src/tools/
├── lsp/
│   ├── index.ts                # Exports all LSP tools
│   ├── client.ts               # LSPClient, LSPServerManager
│   ├── tools.ts                # Tool definitions (6 direct ToolDefinitions)
│   ├── types.ts                # TypeScript interfaces
│   └── constants.ts            # LSP method names, configs
├── ast-grep/
│   ├── index.ts                # Exports AST-Grep tools
│   ├── napi.ts                 # @ast-grep/napi binding
│   ├── tools.ts                # Search and replace tools (2 tools)
│   └── types.ts                # Pattern schemas
└── index.ts                    # Aggregates all tools

Sources: src/tools/AGENTS.md1-109

Key Classes and Functions

File	Key Exports	Purpose
lsp/client.ts	LSPClient, LSPServerManager, lspManager	Manages LSP server lifecycle and communication
lsp/tools.ts	6 direct ToolDefinition objects	LSP tool definitions with parameter validation
ast-grep/napi.ts	createAstGrepInstance	Initializes @ast-grep/napi binding
ast-grep/tools.ts	createAstGrepTools factory	Pattern search and transformation tools

Sources: src/tools/AGENTS.md42-60

Usage Examples

LSP Diagnostics:

AST-Grep Search:

LSP Rename:

Sources: src/tools/AGENTS.md42-60

Anti-Patterns

When using code intelligence tools, avoid these common mistakes:

Anti-Pattern	Correct Approach	Rationale
Sequential LSP calls in loop	Batch operations or delegate to background	Each LSP call has initialization overhead
Text-based search for code	Use ast_grep_search	AST-Grep understands structure, ignores formatting
Manual symbol tracking	Use lsp_find_references	LSP knows all references, including indirect ones
Heavy PreToolUse computation	Move to tool implementation	PreToolUse hooks run on every tool call

Sources: src/tools/AGENTS.md69-75 AGENTS.md76-94