🚀 Enhanced local context with deterministic query-aware retrieval, AST-grep, and actionable intelligence. Provides: (1) deterministic AnswerDraft, (2) ranked JumpTargets, (3) tight MiniBundle (≤3k tokens), (4) NextActions—all using AST + static heuristics. Optional embedding enhancement when available. Completely offline with zero external dependencies for core functionality.

📊 Generate intelligent project navigation hints with word clouds, folder analysis, and architecture detection. Supports multiple output formats including markdown and HTML, with AI-powered analysis and configurable performance options. Accepts absolute paths or relative paths (when workspace can be detected).

📄 Get quick AST-based summary and key symbols for any file. Fast file analysis without external dependencies. Accepts absolute paths or relative paths (when workspace can be detected).

🔍 Map routes, components, data flow, design system, and risks in the web layer with embedding-enhanced analysis. Analyzes Next.js/React projects for architecture insights, component similarities, and potential issues using semantic embeddings.

🐛 Gather comprehensive debug context from error logs and codebase analysis with focused embedding enhancement

When to use:

• When you have error logs, stack traces, or console output to analyze

• When debugging complex issues with multiple file involvement

• When you need to understand error context across the codebase

• Before using AI debugging tools to get structured context

What this does:

• Parses error logs to extract file paths, line numbers, symbols, and error types

• Extracts focused error contexts (~200 characters) for precise embedding queries

• Uses tree-sitter to build symbol indexes for TypeScript/JavaScript/Python files

• Searches codebase for symbol matches with surrounding context

• ENHANCED: Uses semantic embeddings with focused error contexts for better relevance

• Processes each error/warning separately for improved semantic matching

• Ranks matches by relevance (severity, recency, frequency, semantic similarity)

• Returns comprehensive debug report ready for AI analysis

Input: Error logs or stack traces as text Output: Structured debug context report with ranked matches and semantic insights

Performance: Fast local analysis, ~1-3 seconds depending on codebase size Embedding Features: Focused context queries reduce noise and improve relevance

🔍 AST-Grep structural code search tool

Performs powerful structural code search using ast-grep's pattern matching capabilities. Unlike text-based search, this matches syntactical AST node structures.

Key Features:

• Structural pattern matching (not just text)

• Multi-language support (JS, TS, Python, Go, Rust, etc.)

• Wildcard variables ($VAR, $FUNC, $ARGS)

• Precise code location information

• Fast Rust-based execution with performance optimizations

• Comprehensive pattern validation with helpful error messages

• 120-second timeout for very large projects

• Automatic respect for .gitignore files (no manual exclusions needed)

Pattern Syntax:

• Use $ + UPPERCASE for wildcards: $FUNC, $VAR, $ARGS

• Patterns look like real code: 'function $NAME($ARGS) { $BODY }'

• Match specific constructs: 'new $CLASS($ARGS)'

• Valid characters: (), {}, [], "", '', numbers, operators, keywords

• NOT regex: do NOT use '|', '.*', '.+', '/pattern/', or escapes like '(' or '{'.

Common Mistakes to Avoid: ❌ Don't use: 'function $FUNC' (ambiguous, multiple AST interpretations) ❌ Don't use: 'export $TYPE' (ambiguous, multiple AST interpretations) ❌ Don't use: '$NAME' (too generic, matches everything) ❌ Don't use: /pattern/ (regex syntax not supported)

✅ Good Patterns:

• 'function $NAME($ARGS) { $BODY }' (complete function structure)

• 'export const $NAME = $VALUE' (exported constant)

• 'import $NAME from "$MODULE"' (import statement)

• 'new $CLASS($ARGS)' (constructor call)

• 'def ' (Python function definitions)

• 'class $NAME:' (Python class)

• 'await $PROMISE' inside 'for ($COND) { $BODY }' (relational patterns)

Examples:

• Find all functions: 'function $NAME($ARGS) { $BODY }'

• Find all exports: 'export const $NAME = $VALUE'

• Find imports: 'import $NAME from "$MODULE"'

• Find class instantiation: 'new $CLASS($ARGS)'

• Find method calls: '$OBJ.$METHOD($ARGS)'

• Find async functions: 'async function $NAME($ARGS) { $BODY }'

• Find arrow functions: 'const $NAME = ($ARGS) => $BODY'

• Find React components: 'export function $NAME($PROPS) { return $JSX }'

• Find Python function definitions: 'def '

• Find Python classes: 'class $NAME:'

Advanced Usage:

• Use $$$ for zero or more arguments: 'console.log($$$ARGS)'

• Use relational rules: 'await $PROMISE' inside 'for ($COND) { $BODY }'

• Use multiple searches for OR conditions (alternation not supported)

Direct CLI Usage (for agents with command line access): Agents with command line access can run ast-grep directly:

Basic usage

npx ast-grep --pattern "function $NAME($ARGS) { $BODY }" --lang ts

Python function definitions

npx ast-grep --pattern "def " --lang py

Python classes

npx ast-grep --pattern "class $NAME:" --lang py

With file filtering (recommended for large projects)

npx ast-grep --pattern "def " --lang py src/**/*.py

JSON output

npx ast-grep --pattern "class $NAME:" --lang py --json=stream

Full documentation

npx ast-grep --help

Note: ast-grep respects .gitignore files automatically - no --exclude-dir flags needed

Use Cases:

• Code refactoring and migration

• Finding specific patterns across codebase

• Security auditing for dangerous patterns

• Architecture analysis and dependency tracking

• Finding unused imports or exports

• API usage analysis

Performance Optimizations for Large Projects:

• 120-second timeout for very large projects

• Automatically respects .gitignore files for exclusions

• For additional exclusions, configure .gitignore in your project

Tips for Large Projects (like D:\Dev\SWE-agent):

• Use filePattern to search specific directories: "src/**/*.py"

• Add large directories to .gitignore: node_modules/, tests/, docs/, etc.

• Consider CLI usage for better performance: npx ast-grep --pattern "import json" --lang py src/**/*.py