sapient/oh-my-openagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agents): regenerate hierarchical AGENTS.md with init-deep

Browse Source 
- Root AGENTS.md: Updated timestamp, commit hash, line counts
- src/agents/AGENTS.md: Updated to 50 lines, current structure
- src/cli/AGENTS.md: Updated to 57 lines, current structure
- src/features/AGENTS.md: Updated to 65 lines, current structure
- src/hooks/AGENTS.md: Updated to 53 lines, current structure
- src/shared/AGENTS.md: Updated to 52 lines, core utilities
- src/tools/AGENTS.md: Updated to 50 lines, tool categories

🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)
This commit is contained in:
justsisyphus
2026-01-17 19:16:49 +09:00
parent 987ae46841
commit 36b665ed89
7 changed files with 119 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
AGENTS.md
View File

@@ -1,7 +1,7 @@
# PROJECT KNOWLEDGE BASE
**Generated:** 2026-01-15T14:53:00+09:00
**Commit:** 89fa9ff1
**Generated:** 2026-01-17T19:00:25+09:00
**Commit:** 987ae468
**Branch:** dev
## OVERVIEW
@@ -21,7 +21,7 @@ oh-my-opencode/
│ ├── cli/ # CLI installer, doctor - see src/cli/AGENTS.md
│ ├── mcp/ # MCP configs: context7, grep_app, websearch
│ ├── config/ # Zod schema, TypeScript types
│ └── index.ts # Main plugin entry (580 lines)
│ └── index.ts # Main plugin entry (568 lines)
├── script/ # build-schema.ts, publish.ts, generate-changelog.ts
├── assets/ # JSON schema
└── dist/ # Build output (ESM + .d.ts)
@@ -48,7 +48,7 @@ oh-my-opencode/
| Shared utilities | `src/shared/` | Cross-cutting utilities |
| Slash commands | `src/hooks/auto-slash-command/` | Auto-detect and execute `/command` patterns |
| Ralph Loop | `src/hooks/ralph-loop/` | Self-referential dev loop until completion |
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (684 lines) |
| Orchestrator | `src/hooks/sisyphus-orchestrator/` | Main orchestration hook (771 lines) |
## TDD (Test-Driven Development)
@@ -160,18 +160,17 @@ bun test # Run tests (80+ test files, 2500+ BDD assertions)
| File | Lines | Description |
|------|-------|-------------|
| `src/agents/orchestrator-sisyphus.ts` | 1485 | Orchestrator agent, 7-section delegation, accumulated wisdom |
| `src/features/builtin-skills/skills.ts` | 1230 | Skill definitions (frontend-ui-ux, playwright) |
| `src/agents/prometheus-prompt.ts` | 991 | Planning agent, interview mode, multi-agent validation |
| `src/features/background-agent/manager.ts` | 928 | Task lifecycle, concurrency |
| `src/agents/orchestrator-sisyphus.ts` | 1531 | Orchestrator agent, 7-section delegation, accumulated wisdom |
| `src/features/builtin-skills/skills.ts` | 1203 | Skill definitions (frontend-ui-ux, playwright) |
| `src/agents/prometheus-prompt.ts` | 1196 | Planning agent, interview mode, multi-agent validation |
| `src/features/background-agent/manager.ts` | 1165 | Task lifecycle, concurrency |
| `src/hooks/sisyphus-orchestrator/index.ts` | 771 | Orchestrator hook impl |
| `src/tools/delegate-task/tools.ts` | 770 | Category-based task delegation |
| `src/cli/config-manager.ts` | 730 | JSONC parsing, multi-level config, env detection |
| `src/hooks/sisyphus-orchestrator/index.ts` | 684 | Orchestrator hook impl |
| `src/tools/sisyphus-task/tools.ts` | 667 | Category-based task delegation |
| `src/agents/sisyphus.ts` | 643 | Main Sisyphus prompt |
| `src/tools/lsp/client.ts` | 632 | LSP protocol, JSON-RPC |
| `src/agents/sisyphus.ts` | 640 | Main Sisyphus prompt |
| `src/features/builtin-commands/templates/refactor.ts` | 619 | Refactoring command template |
| `src/index.ts` | 580 | Main plugin, all hook/tool init |
| `src/hooks/anthropic-context-window-limit-recovery/executor.ts` | 554 | Multi-stage recovery |
| `src/tools/lsp/client.ts` | 596 | LSP protocol, JSON-RPC |
| `src/index.ts` | 568 | Main plugin, all hook/tool init |
## MCP ARCHITECTURE

31
src/agents/AGENTS.md
View File

@@ -6,8 +6,8 @@ AI agent definitions for multi-model orchestration, delegating tasks to speciali
## STRUCTURE
```
agents/
├── orchestrator-sisyphus.ts # Orchestrator agent (1485 lines) - 7-section delegation, wisdom
├── sisyphus.ts # Main Sisyphus prompt (643 lines)
├── orchestrator-sisyphus.ts # Orchestrator agent (1531 lines) - 7-section delegation, wisdom
├── sisyphus.ts # Main Sisyphus prompt (640 lines)
├── sisyphus-junior.ts # Junior variant for delegated tasks
├── oracle.ts # Strategic advisor (GPT-5.2)
├── librarian.ts # Multi-repo research (GLM-4.7-free)
@@ -15,7 +15,7 @@ agents/
├── frontend-ui-ux-engineer.ts # UI generation (Gemini 3 Pro Preview)
├── document-writer.ts # Technical docs (Gemini 3 Pro Preview)
├── multimodal-looker.ts # PDF/image analysis (Gemini 3 Flash)
├── prometheus-prompt.ts # Planning agent prompt (991 lines) - interview mode
├── prometheus-prompt.ts # Planning agent prompt (1196 lines) - interview mode
├── metis.ts # Plan Consultant agent - pre-planning analysis
├── momus.ts # Plan Reviewer agent - plan validation
├── build-prompt.ts # Shared build agent prompt
@@ -26,19 +26,6 @@ agents/
└── index.ts # builtinAgents export
```
## AGENT MODELS
| Agent | Default Model | Purpose |
|-------|---------------|---------|
| Sisyphus | anthropic/claude-opus-4-5 | Primary orchestrator. 32k extended thinking budget. |
| oracle | openai/gpt-5.2 | High-IQ debugging, architecture, strategic consultation. |
| librarian | opencode/glm-4.7-free | Multi-repo analysis, docs research, GitHub examples. |
| explore | opencode/grok-code | Fast contextual grep. Fallbacks: Gemini-3-Flash, Haiku-4-5. |
| frontend-ui-ux | google/gemini-3-pro-preview | Production-grade UI/UX generation and styling. |
| document-writer | google/gemini-3-pro-preview | Technical writing, guides, API documentation. |
| Prometheus | anthropic/claude-opus-4-5 | Strategic planner. Interview mode, orchestrates Metis/Momus. |
| Metis | anthropic/claude-sonnet-4-5 | Plan Consultant. Pre-planning risk/requirement analysis. |
| Momus | anthropic/claude-sonnet-4-5 | Plan Reviewer. Validation and quality enforcement. |
## HOW TO ADD AN AGENT
1. Create `src/agents/my-agent.ts` exporting `AgentConfig`.
2. Add to `builtinAgents` in `src/agents/index.ts`.
@@ -50,12 +37,14 @@ agents/
2. Environment-specific settings (max20, antigravity).
3. Hardcoded defaults in `index.ts`.
## SHARED PROMPTS
- **7-Section Delegation**: `orchestrator-sisyphus.ts` uses strict phases (0-6) for classification, research, planning, validation.
- **Wisdom Notepad**: Persistent scratchpad preserving project-specific learnings across turns.
- **Interview Mode**: `Prometheus` defaults to conversational consultant mode for requirement extraction.
- **build-prompt.ts**: Unified base for Sisyphus and Builder variants.
- **plan-prompt.ts**: Core planning logic shared across planning agents.
## ANTI-PATTERNS
- **Trusting reports**: NEVER trust subagent self-reports; always verify outputs.
- **High temp**: Don't use >0.3 for code agents (Sisyphus/Prometheus use 0.1).
- **Sequential calls**: Prefer `delegate_task` with `run_in_background` for parallelism.
## SHARED PROMPTS
- **build-prompt.ts**: Unified base for Sisyphus and Builder variants.
- **plan-prompt.ts**: Core planning logic shared across planning agents.
- **orchestrator-sisyphus.ts**: Uses a 7-section prompt structure and "wisdom notepad" to preserve learnings across turns.

2
src/cli/AGENTS.md
View File

@@ -6,7 +6,7 @@ CLI for oh-my-opencode: interactive installer, health diagnostics (doctor), runt
## STRUCTURE
```
cli/
├── index.ts # Commander.js entry, subcommand routing (146 lines)
├── index.ts # Commander.js entry, subcommand routing
├── install.ts # Interactive TUI installer (462 lines)
├── config-manager.ts # JSONC parsing, env detection (730 lines)
├── types.ts # CLI-specific types

52
src/features/AGENTS.md
View File

@@ -6,25 +6,23 @@ Claude Code compatibility layer + core feature modules. Commands, skills, agents
## STRUCTURE
```
features/
├── background-agent/ # Task lifecycle, notifications (928 lines manager.ts)
├── boulder-state/ # Boulder state persistence
├── builtin-commands/ # Built-in slash commands
│ └── templates/ # start-work, refactor, init-deep, ralph-loop
├── builtin-skills/ # Built-in skills (1230 lines skills.ts)
│ ├── git-master/ # Atomic commits, rebase, history search
│ ├── playwright # Browser automation skill
│ └── frontend-ui-ux/ # Designer-turned-developer skill
├── background-agent/ # Task lifecycle, notifications (1165 lines manager.ts)
├── boulder-state/ # Boulder/Todo state persistence
├── builtin-commands/ # Built-in slash commands (ralph-loop, refactor, init-deep)
├── builtin-skills/ # Built-in skills (1203 lines skills.ts)
│ ├── git-master/ # Atomic commits, history search
│ ├── playwright/ # Browser automation
│ └── frontend-ui-ux/ # Designer-developer skill
├── claude-code-agent-loader/ # ~/.claude/agents/*.md
├── claude-code-command-loader/ # ~/.claude/commands/*.md
├── claude-code-mcp-loader/ # .mcp.json files
│ └── env-expander.ts # ${VAR} expansion
├── claude-code-mcp-loader/ # .mcp.json files with ${VAR} expansion
├── claude-code-plugin-loader/ # installed_plugins.json
├── claude-code-session-state/ # Session state persistence
├── context-injector/ # Context collection and injection
├── context-injector/ # AGENTS.md/README.md/Rules injection
├── opencode-skill-loader/ # Skills from OpenCode + Claude paths
├── skill-mcp-manager/ # MCP servers in skill YAML
├── task-toast-manager/ # Task toast notifications
└── hook-message-injector/ # Inject messages into conversation
├── skill-mcp-manager/ # MCP servers in skill YAML (stdio/http transports)
├── task-toast-manager/ # Task status toast notifications
└── hook-message-injector/ # Message injection into conversation streams
```
## LOADER PRIORITY
@@ -36,7 +34,7 @@ features/
| MCPs | `.claude/.mcp.json` > `.mcp.json` > `~/.claude/.mcp.json` |
## CONFIG TOGGLES
```json
```jsonc
{
"claude_code": {
"mcp": false, // Skip .mcp.json
@@ -49,19 +47,19 @@ features/
```
## BACKGROUND AGENT
- Lifecycle: pending → running → completed/failed
- Concurrency limits per provider/model (manager.ts)
- `background_output` to retrieve results, `background_cancel` for cleanup
- Automatic task expiration and cleanup logic
- **Lifecycle**: `launch` → `poll` (idle/stability detection) → `complete`.
- **Concurrency**: Per-provider/model limits in `concurrency.ts`.
- **Notification**: Auto-injects system reminders into parent session on task completion.
- **Cleanup**: Shutdown handler cancels pending waiters; idle tasks pruning (30m TTL).
## SKILL MCP
- MCP servers embedded in skill YAML frontmatter
- Lazy client loading via `skill-mcp-manager`
- `skill_mcp` tool for cross-skill tool discovery
- Session-scoped MCP server lifecycle management
- **Lazy Loading**: Clients connect on first tool call via `SkillMcpManager`.
- **Transports**: `stdio` (local process) or `http` (SSE/Streamable HTTP).
- **Environment**: `${VAR}` expansion in config via `env-expander.ts`.
- **Lifecycle**: Session-scoped clients; auto-cleanup after 5m idle.
## ANTI-PATTERNS
- Sequential execution for independent tasks (use `delegate_task`)
- Trusting agent self-reports without verification
- Blocking main thread during loader initialization
- Manual version bumping in `package.json`
- **Sequential Delegation**: Calling agents one-by-one; use `delegate_task` for parallel runs.
- **Self-Report Trust**: Trusting agent's "I'm done" without verifying against session state.
- **Main Thread Blocks**: Heavy I/O or long-running logic during loader initialization.
- **Manual Versioning**: Updating `package.json` version field; managed exclusively by CI.

13
src/hooks/AGENTS.md
View File

@@ -6,12 +6,12 @@
## STRUCTURE
```
hooks/
├── sisyphus-orchestrator/ # Main orchestration & agent delegation (684 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (554 lines)
├── todo-continuation-enforcer.ts # Force completion of [ ] items (445 lines)
├── ralph-loop/ # Self-referential dev loop (364 lines)
├── claude-code-hooks/ # settings.json hook compatibility layer
├── comment-checker/ # Prevents AI slop/excessive comments
├── sisyphus-orchestrator/ # Main orchestration & agent delegation (771 lines)
├── anthropic-context-window-limit-recovery/ # Auto-summarize at token limit (14 files)
├── todo-continuation-enforcer.ts # Force completion of [ ] items
├── ralph-loop/ # Self-referential dev loop (7 files)
├── claude-code-hooks/ # settings.json hook compatibility layer (13 files)
├── comment-checker/ # Prevents AI slop/excessive comments (13 files)
├── auto-slash-command/ # Detects and executes /command patterns
├── rules-injector/ # Conditional rules from .claude/rules/
├── directory-agents-injector/ # Auto-injects local AGENTS.md files
@@ -21,7 +21,6 @@ hooks/
├── thinking-block-validator/ # Ensures valid <thinking> format
├── context-window-monitor.ts # Reminds agents of remaining headroom
├── session-recovery/ # Auto-recovers from session crashes
├── start-work/ # Initializes work sessions (ulw/ulw)
├── think-mode/ # Dynamic thinking budget adjustment
├── background-notification/ # OS notification on task completion
└── tool-output-truncator.ts # Prevents context bloat from verbose tools

84
src/shared/AGENTS.md
View File

@@ -1,74 +1,52 @@
# SHARED UTILITIES KNOWLEDGE BASE
## OVERVIEW
Cross-cutting utilities for path resolution, config management, text processing, and Claude Code compatibility.
Core cross-cutting utilities for path resolution, token-safe text processing, and Claude Code compatibility.
## STRUCTURE
```
shared/
├── index.ts # Barrel export
├── agent-variant.ts # Agent model/prompt variation logic
├── claude-config-dir.ts # ~/.claude resolution
├── command-executor.ts # Shell exec with variable expansion
├── config-errors.ts # Global error tracking
├── config-path.ts # User/project config paths
├── data-path.ts # XDG data directory
├── deep-merge.ts # Type-safe recursive merge
├── dynamic-truncator.ts # Token-aware truncation
├── external-plugin-detector.ts # Detect marketplace plugins
├── file-reference-resolver.ts # @filename syntax
├── file-utils.ts # Symlink, markdown detection
├── first-message-variant.ts # Initial prompt variations
├── frontmatter.ts # YAML frontmatter parsing
├── hook-disabled.ts # Check if hook disabled
├── jsonc-parser.ts # JSON with Comments
├── logger.ts # File-based logging
├── migration.ts # Legacy name compat (omo → Sisyphus)
├── model-sanitizer.ts # Normalize model names
├── opencode-config-dir.ts # ~/.config/opencode resolution
├── opencode-version.ts # Version comparison logic
├── pattern-matcher.ts # Tool name matching
├── permission-compat.ts # Legacy permission mapping
├── session-cursor.ts # Track message history pointer
├── snake-case.ts # Case conversion
├── tool-name.ts # PascalCase normalization
└── zip-extractor.ts # Plugin installation utility
├── logger.ts # Persistent file-based logging (tmpdir/oh-my-opencode.log)
├── permission-compat.ts # Agent tool restrictions (ask/allow/deny)
├── dynamic-truncator.ts # Token-aware truncation with context headroom
├── frontmatter.ts # YAML frontmatter parsing with JSON_SCHEMA safety
├── jsonc-parser.ts # JSON with Comments support for config files
├── data-path.ts # XDG-compliant storage paths (~/.local/share)
├── opencode-config-dir.ts # Resolve ~/.config/opencode for CLI/Desktop
├── claude-config-dir.ts # Resolve ~/.claude for compatibility
├── migration.ts # Legacy name mapping (omo -> Sisyphus)
└── opencode-version.ts # Version comparison logic (e.g., >= 1.0.150)
```
## WHEN TO USE
| Task | Utility |
|------|---------|
| Find ~/.claude | `getClaudeConfigDir()` |
| Find ~/.config/opencode | `getOpenCodeConfigDir()` |
| Merge configs | `deepMerge(base, override)` |
| Parse user files | `parseJsonc()` |
| Check hook enabled | `isHookDisabled(name, list)` |
| Truncate output | `dynamicTruncate(text, budget)` |
| Resolve @file | `resolveFileReferencesInText()` |
| Execute shell | `resolveCommandsInText()` |
| Legacy names | `migrateLegacyAgentNames()` |
| Version check | `isOpenCodeVersionAtLeast(version)` |
| Map permissions | `normalizePermission()` |
| Track session | `SessionCursor` |
| Debugging/Auditing | `log(message, data)` in `logger.ts` |
| Limit agent context | `dynamicTruncate(ctx, sessionId, output)` |
| Parse rule meta | `parseFrontmatter(content)` |
| Load user configs | `parseJsonc(text)` or `readJsoncFile(path)` |
| Restrict tools | `createAgentToolAllowlist(tools)` |
| Resolve app paths | `getOpenCodeConfigDir()` or `getClaudeConfigDir()` |
| Update legacy config | `migrateConfigFile(path, rawConfig)` |
## CRITICAL PATTERNS
```typescript
// Dynamic truncation with context budget
const output = dynamicTruncate(result, remainingTokens, 0.5)
// Truncate large output based on 50% remaining context window
const { result } = await dynamicTruncate(ctx, sessionID, largeBuffer);
// Config resolution priority
const final = deepMerge(deepMerge(defaults, userConfig), projectConfig)
// Safe config loading with comment/trailing comma support
const settings = readJsoncFile<Settings>(configPath);
// Safe JSONC parsing for user-edited files
const { config, error } = parseJsoncSafe(content)
// Version-gated logic for OpenCode 1.1.0+
if (isOpenCodeVersionAtLeast("1.1.0")) { /* ... */ }
// Version-gated features
if (isOpenCodeVersionAtLeast('1.0.150')) { /* ... */ }
// Permission normalization for agent tools
const permissions = migrateToolsToPermission(legacyTools);
```
## ANTI-PATTERNS
- Hardcoding paths (use `getClaudeConfigDir`, `getOpenCodeConfigDir`)
- Using `JSON.parse` for user configs (always use `parseJsonc`)
- Ignoring output size (large tool outputs MUST use `dynamicTruncate`)
- Manual version parsing (use `opencode-version.ts` utilities)
- Raw permission checks (use `permission-compat.ts`)
- Raw `JSON.parse` for configs (use `jsonc-parser.ts`)
- Hardcoded `~/.claude` (use `claude-config-dir.ts`)
- `console.log` for background agents (use `logger.ts`)
- Unbounded tool output (always use `dynamic-truncator.ts`)
- Manual version parsing (use `opencode-version.ts`)

76
src/tools/AGENTS.md
View File

@@ -1,60 +1,50 @@
# TOOLS KNOWLEDGE BASE
## OVERVIEW
Custom tools extending agent capabilities: LSP (3 tools), AST-aware search/replace, background tasks, and multimodal analysis.
Core toolset implementing LSP, structural search, and system orchestration. Extends OpenCode with high-performance C++ bindings and multi-agent delegation.
## STRUCTURE
```
tools/
├── ast-grep/ # AST-aware search/replace (25 languages)
│ ├── cli.ts # @ast-grep/cli fallback
│ └── napi.ts # @ast-grep/napi native binding (preferred)
├── background-task/ # Async agent task management
├── call-omo-agent/ # Spawn explore/librarian agents
├── glob/ # File pattern matching (timeout-safe)
├── grep/ # Content search (timeout-safe)
├── interactive-bash/ # Tmux session management
├── look-at/ # Multimodal analysis (PDF, images)
├── lsp/ # IDE-like code intelligence
│ ├── client.ts # LSP connection lifecycle (632 lines)
│ ├── tools.ts # Tool implementations
│ └── config.ts, types.ts, utils.ts
├── session-manager/ # OpenCode session history management
├── sisyphus-task/ # Category-based delegation (667 lines)
├── skill/ # Skill loading/execution
├── skill-mcp/ # Skill-embedded MCP invocation
├── slashcommand/ # Slash command execution
└── index.ts # builtinTools export (75 lines)
├── [tool-name]/
│ ├── index.ts # Tool factory entry
│ ├── tools.ts # Business logic & implementation
│ ├── types.ts # Zod schemas & TS types
│ └── constants.ts # Tool-specific fixed values
├── lsp/ # 11 tools via JSON-RPC client (596 lines client.ts)
├── ast-grep/ # Structural search (NAPI bindings)
├── delegate-task/ # Category-based agent routing (770 lines tools.ts)
├── session-manager/ # OpenCode session history (9 files)
└── interactive-bash/ # Tmux session management (5 files)
```
## TOOL CATEGORIES
| Category | Tools | Purpose |
|----------|-------|---------|
| LSP | lsp_diagnostics, lsp_prepare_rename, lsp_rename | IDE-grade code intelligence (3 tools) |
| AST | ast_grep_search, ast_grep_replace | Structural pattern matching/rewriting |
| Search | grep, glob | Timeout-safe file and content search |
| Session | session_list, session_read, session_search, session_info | History navigation and retrieval |
| Background | delegate_task, background_output, background_cancel | Parallel agent orchestration |
| UI/Terminal | look_at, interactive_bash | Visual analysis and tmux control |
| Execution | slashcommand, skill, skill_mcp | Command and skill-based extensibility |
| Category | Purpose | Key Implementations |
|----------|---------|---------------------|
| **LSP** | Semantic code intelligence | `lsp_goto_definition`, `lsp_find_references`, `lsp_rename` |
| **Search** | Fast discovery & matching | `glob`, `grep`, `ast_grep_search`, `ast_grep_replace` |
| **System** | CLI & Environment | `bash`, `interactive_bash` (tmux), `look_at` (vision) |
| **Session** | History & Context | `session_read`, `session_search`, `session_select` |
| **Agent** | Task Orchestration | `delegate_task`, `call_omo_agent` |
## HOW TO ADD A TOOL
1. Create directory `src/tools/my-tool/`.
2. Implement `tools.ts` (factory), `types.ts`, and `constants.ts`.
3. Export via `index.ts` and register in `src/tools/index.ts`.
## HOW TO ADD
1. **Directory**: Create `src/tools/[name]/` with standard files.
2. **Factory**: Use `tool()` from `@opencode-ai/plugin/tool`.
3. **Parameters**: Define strict Zod schemas in `types.ts`.
4. **Registration**: Export from `src/tools/index.ts` and add to `builtinTools`.
## LSP SPECIFICS
- **Lifecycle**: Lazy initialization on first call; auto-shutdown on idle.
- **Config**: Merges `opencode.json` and `oh-my-opencode.json`.
- **Capability**: Supports full LSP spec including `rename` and `prepareRename`.
- **Client**: `lsp/client.ts` manages stdio lifecycle and JSON-RPC.
- **Capabilities**: Supports definition, references, symbols, diagnostics, and workspace-wide rename.
- **Protocol**: Maps standard LSP methods to tool-compatible responses.
## AST-GREP SPECIFICS
- **Precision**: Uses tree-sitter for structural matching (avoids regex pitfalls).
- **Binding**: Uses `@ast-grep/napi` for performance; ensure patterns are valid AST nodes.
- **Variables**: Supports `$VAR` and `$$$` meta-variables for capture.
- **Engine**: Uses `@ast-grep/napi` for 25+ language support.
- **Patterns**: Supports meta-variables (`$VAR`) and multi-node matching (`$$$`).
- **Performance**: Structural matching executed in Rust/C++ layer.
## ANTI-PATTERNS
- **Sync Ops**: Never use synchronous file I/O; blocking the main thread kills responsiveness.
- **No Timeouts**: Always wrap external CLI/LSP calls in timeouts (default 60s).
- **Direct Subprocess**: Avoid raw `spawn` for ast-grep; use NAPI binding.
- **Manual Pathing**: Use `shared/utils` for path normalization across platforms.
- **Sequential Calls**: Don't call `bash` in loops; use `&&` or delegation.
- **Raw File Ops**: Never use `mkdir/touch` inside tool logic.
- **Heavy Sync**: Keep `PreToolUse` light; heavy computation belongs in `tools.ts`.
- **Sleep**: Never use `sleep N`; use polling loops or tool-specific wait flags.