sgrep - Semantic Grep

A command-line tool for semantic code understanding. Unlike traditional grep that matches text patterns, sgrep understands code by meaning - ask questions about your codebase and get intelligent answers with code references.

Powered by the Augment SDK.

Installation

From npm

# Install globally
npm install -g @pimzino/sgrep

# Or use with npx
npx @pimzino/sgrep "how does authentication work?"

Claude Code Integration

Install sgrep for Claude Code:

sgrep install-claude-code

This adds the sgrep skill to Claude Code, allowing you to use semantic search directly in your AI coding sessions.

Prerequisites

Before using sgrep, you need to:

1. Install the auggie CLI:

   npm install -g @augmentcode/auggie@latest

2. Login to Augment:

   auggie login

Usage

Ask Questions (Default Command)

Get explanations about how code works:

# Ask about the codebase (default command)
sgrep "How does the auth flow work?"

# Ask about specific directory
sgrep "What patterns are used for API endpoints?" ./api

# Ask about implementation details
sgrep "How is the database accessed?"

# Explicit ask command
sgrep ask "How does routing work?"

Semantic Search

Search for code by describing what it does:

# Search for code by meaning
sgrep search "authentication middleware"

# Search in specific directory
sgrep search "database connection setup" ./src

# Limit results
sgrep search -m 5 "user login handling"

Enhance Prompts

Improve vague prompts with codebase context:

# Enhance a simple prompt
sgrep enhance "fix the bug"

# Enhance with specific directory context
sgrep enhance "add authentication" ./my-project

# JSON output
sgrep enhance "refactor this" --json

Watch Mode

Keep the index up-to-date with live file watching:

# Watch current directory
sgrep watch

# Watch specific directory
sgrep watch ./my-project

# Write PID to file (for daemon management)
sgrep watch --pid-file /tmp/sgrep.pid

Output shows real-time index updates:

[10:32:15] + added: src/newfile.ts (143 total)
[10:32:47] ~ updated: src/utils/helper.ts (143 total)
[10:33:02] - removed: src/oldfile.ts (142 total)

The --pid-file option is used internally by the Claude Code hooks to manage the background watch process.

Options

| Option | Short | Description | |--------|-------|-------------| | --dir <path> | -d | Directory to search (default: cwd) | | --max-results <n> | -m | Limit number of results (search only) | | --json | -j | Output results as JSON | | --no-color | | Disable colored output | | --debug | | Enable verbose debug logging | | --pid-file <path> | | Write PID to file (watch command only) | | --version | -v | Show version | | --help | -h | Show help |

Commands

| Command | Description | |---------|-------------| | sgrep <question> | Ask a question about the codebase (default) | | sgrep ask <question> | Ask a question about the codebase | | sgrep search <query> | Semantic search for code | | sgrep enhance <prompt> | Enhance a prompt with codebase context | | sgrep watch | Watch for file changes and keep index updated | | sgrep install-claude-code | Install Claude Code plugin | | sgrep uninstall-claude-code | Uninstall Claude Code plugin |

Examples

# Ask about the codebase (default command)
sgrep "How does user authentication work?"

# Ask with path as positional argument
sgrep "What is the API architecture?" ./packages/api

# Semantic search for code
sgrep search "error handling patterns"

# JSON output for piping
sgrep "What testing frameworks are used?" --json | jq '.answer'

# Debug mode for troubleshooting
sgrep --debug "How are database models structured?"

# Enhance a vague instruction
sgrep enhance "fix the login issue"

# Watch for changes
sgrep watch ./src

Configuration

sgrep supports configuration via files with cascading priority:

1. CLI flags (highest priority)
2. Environment variables
3. Local config file (.sgreprc.json in cwd or parent dirs)
4. Global config file (~/.config/sgrep/config.json)

Config File Format

Create a .sgreprc.json file:

{
  "defaultDir": "./src",
  "maxResults": 10,
  "outputFormat": "pretty"
}

Environment Variables

| Variable | Description | |----------|-------------| | SGREP_DIR | Default directory to search | | SGREP_DEBUG | Enable debug mode for CLI and hooks (true or 1) | | SGREP_MAX_RESULTS | Default max results | | SGREP_FORMAT | Output format (json or pretty) | | NO_COLOR | Disable colors (standard) | | SGREP_NO_COLOR | Disable colors (sgrep-specific) |

Hook Debug Logging

When using the Claude Code integration, set SGREP_DEBUG=1 to enable detailed logging for troubleshooting hooks:

# Enable debug logging for hooks
set SGREP_DEBUG=1  # Windows
export SGREP_DEBUG=1  # Linux/macOS

Debug logs are written to:

• %TEMP%\sgrep-enhance.log - Prompt enhancement hook
• %TEMP%\sgrep-watch.log - Session start hook
• %TEMP%\sgrep-watch-kill.log - Session end hook

How It Works

sgrep uses the Augment SDK's DirectContext to:

1. Index your codebase - Builds a semantic understanding of your code
2. Watch for changes - Incrementally updates the index when files change
3. Search by meaning - Finds code that matches your description, not just text patterns
4. Answer questions - Synthesizes explanations from relevant code sections
5. Enhance prompts - Improves vague instructions with codebase context

This makes it powerful for:

• Exploring unfamiliar codebases
• Finding implementations without knowing exact names
• Understanding how systems work
• Discovering related code across files
• Improving AI prompts with relevant context

Comparison with grep/ripgrep

| Feature | grep/rg | sgrep | |---------|---------|-------| | Text pattern matching | Yes | No | | Regex support | Yes | No | | Find by functionality | No | Yes | | Understands code semantics | No | Yes | | Ask questions | No | Yes | | Enhance prompts | No | Yes | | Live file watching | No | Yes | | Speed | Instant | ~100-500ms |

Use grep/rg when: You know the exact text, variable name, or pattern to search for.

Use sgrep when: You want to find code by what it does, or understand how something works.

Claude Code Integration

sgrep install-claude-code

Adds the /sgrep skill to Claude Code for semantic searches directly in your coding sessions.

Features installed:

• Skill (/sgrep) - Use semantic search directly in Claude Code conversations
• SessionStart Hook - Automatically starts sgrep watch in the background when Claude Code starts, keeping the index warm for fast searches
• SessionEnd Hook - Cleanly shuts down the background watch process when Claude Code exits
• UserPromptSubmit Hook - Optionally enhances your prompts with codebase context before sending to Claude (shows a confirmation dialog on Windows)

Uninstalling

sgrep uninstall-claude-code

Troubleshooting

"Authentication Error"

Make sure you've logged in:

auggie login

"Directory does not exist"

Check the path you're providing:

# Use absolute or relative path
sgrep "query" /absolute/path
sgrep "query" ./relative/path

Slow first search

The first search indexes the codebase, which can take a moment for large projects. Subsequent searches reuse the index.

Debug mode

Use --debug to see what's happening:

sgrep --debug "your query"

Claude Code hooks not working

1. Check the plugin is installed:

   # Look for sgrep in Claude Code plugins
   cat ~/.claude/settings.json | grep -A5 "plugins"

2. Check the cache has the latest version:

   # Windows - clear the plugin cache and reinstall
   Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache\sgrep"
   sgrep uninstall-claude-code
   sgrep install-claude-code

3. Enable debug logging:

   # Set environment variable before starting Claude Code
   set SGREP_DEBUG=1  # Windows
   export SGREP_DEBUG=1  # Linux/macOS

4. Check the debug logs:

   • Windows: %TEMP%\sgrep-watch.log, %TEMP%\sgrep-enhance.log
   • Linux/macOS: /tmp/sgrep-watch.log, /tmp/sgrep-enhance.log

Watch process not starting

If the background watch process isn't starting on Claude Code session start:

1. Check sgrep is in PATH:

   where sgrep  # Windows
   which sgrep  # Linux/macOS

2. Try running watch manually:

   sgrep watch --debug

3. Check for existing PID files:

   # Windows
   dir %TEMP%\sgrep-watch-pid-*
   
   # Linux/macOS
   ls /tmp/sgrep-watch-pid-*

License

MIT