diff --git a/AGENTS.md b/AGENTS.md index 2ee441483..50ac5f758 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/src/agents/AGENTS.md b/src/agents/AGENTS.md index cdadaa2b2..f7b56cf3c 100644 --- a/src/agents/AGENTS.md +++ b/src/agents/AGENTS.md @@ -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. diff --git a/src/cli/AGENTS.md b/src/cli/AGENTS.md index ff4083416..88ae9b7a6 100644 --- a/src/cli/AGENTS.md +++ b/src/cli/AGENTS.md @@ -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 diff --git a/src/features/AGENTS.md b/src/features/AGENTS.md index 64cc94b40..ab1069376 100644 --- a/src/features/AGENTS.md +++ b/src/features/AGENTS.md @@ -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. diff --git a/src/hooks/AGENTS.md b/src/hooks/AGENTS.md index 7a24a794a..dd879882e 100644 --- a/src/hooks/AGENTS.md +++ b/src/hooks/AGENTS.md @@ -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 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 diff --git a/src/shared/AGENTS.md b/src/shared/AGENTS.md index 0161968be..b1614d8ad 100644 --- a/src/shared/AGENTS.md +++ b/src/shared/AGENTS.md @@ -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(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`) diff --git a/src/tools/AGENTS.md b/src/tools/AGENTS.md index 0d9c82528..f9534eb88 100644 --- a/src/tools/AGENTS.md +++ b/src/tools/AGENTS.md @@ -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.