npm package: @pimzino/sgrep
Description: Semantic grep - search codebases by meaning using the Augment SDK
Author: pimzino
Latest version: 1.3.48

# 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](https://www.augmentcode.com/).

## Installation

### From npm

```bash
# 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:

```bash
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:
   ```bash
   npm install -g @augmentcode/auggie@latest
   ```

2. Login to Augment:
   ```bash
   auggie login
   ```

## Usage

### Ask Questions (Default Command)

Get explanations about how code works:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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:

```json
{
  "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:

```bash
# 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

```bash
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

```bash
sgrep uninstall-claude-code
```

## Troubleshooting

### "Authentication Error"

Make sure you've logged in:
```bash
auggie login
```

### "Directory does not exist"

Check the path you're providing:
```bash
# 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:
```bash
sgrep --debug "your query"
```

### Claude Code hooks not working

1. **Check the plugin is installed:**
   ```bash
   # Look for sgrep in Claude Code plugins
   cat ~/.claude/settings.json | grep -A5 "plugins"
   ```

2. **Check the cache has the latest version:**
   ```bash
   # 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:**
   ```bash
   # 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:**
   ```bash
   where sgrep  # Windows
   which sgrep  # Linux/macOS
   ```

2. **Try running watch manually:**
   ```bash
   sgrep watch --debug
   ```

3. **Check for existing PID files:**
   ```bash
   # Windows
   dir %TEMP%\sgrep-watch-pid-*

   # Linux/macOS
   ls /tmp/sgrep-watch-pid-*
   ```

## License

MIT