deep-hook 0.1.1
AI-powered Git pre-push code review using Cursor
License: MIT
Requires Python: >=3.9
Keywords: git, code-review, ai, pre-push, hook, cursor

# 🔗 Deep Hook

AI-powered Git pre-push code review using Cursor agent.

## What it does

Runs a thorough code review before every push, catching bugs and issues while you still have context.

```
╭─ 🔗 Deep Hook ──────────────────────────────────────────╮
│             AI-Powered Code Review                        │
╰──────────────────────────────────────────────────────────╯

Comparing against: origin/main

╭─ 📊 Diff Stats ───────────────────────────────────────────╮
│ 3 files | +45 | -12                                       │
╰──────────────────────────────────────────────────────────╯

╭─ 🧠 TL;DR ────────────────────────────────────────────────╮
│ • Added user authentication                               │
│ • Refactored API client                                   │
╰──────────────────────────────────────────────────────────╯

╭─ ❌ Critical ─────────────────────────────────────────────╮
│ • `auth.dart:45` — Token stored without encryption        │
╰──────────────────────────────────────────────────────────╯

🚫 Push Blocked — Critical issues found.
Continue with push? (y/N)
```

## Install

```bash
pip install deep-hook
cd your-project
deep-hook install
deep-hook init
```

## Commands

```bash
deep-hook review    # Run by pre-push hook
deep-hook check     # Manual review (dry run)
deep-hook install   # Install hook
deep-hook uninstall # Remove hook
deep-hook init      # Create config
```

## Configuration

Create `deep.yml` in your project root:

```yaml
# Branch to compare against
base_branch: main

# Project language
language: flutter  # flutter, python, typescript, go, rust, other

# Cursor agent timeout (seconds)
timeout: 120

# Max diff lines
max_diff_lines: 3000

# Cursor agent model
model: gpt-5.2-codex-fast

# Guidelines for the AI
guidelines:
  - "Use BLoC pattern"
  - "No print() in production"
```

## Bypass

```bash
git push --no-verify
# or
DEEP_SKIP=1 git push
```

## Requirements

### System Requirements

- **Python**: 3.9 or higher
- **Git**: 2.x or higher (for repository operations)
- **Cursor**: Latest version with CLI enabled

### Cursor Setup

1. Install [Cursor](https://cursor.com) if not already installed
2. Open Cursor
3. Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Linux/Windows)
4. Search for: **"Install cursor command"**
5. Verify installation:
   ```bash
   cursor --version
   cursor agent --help
   ```

### Git Setup

Deep Hook requires a Git repository. Ensure Git is installed and configured:

```bash
git --version  # Should be 2.x or higher
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

## How it works

1. Pre-push hook triggers `deep-hook review`
2. Diff is extracted (comparing against `base_branch`)
3. Cursor agent analyzes the diff
4. Review is displayed with Rich formatting
5. Critical issues block push (with option to continue)
6. Optionally saves `REVIEW_SUGGESTIONS.md`

## Security & Privacy

### Data Handling

- **Local Processing**: All code review happens locally on your machine
- **No Telemetry**: Deep Hook does not collect or transmit any data
- **Cursor Agent**: Code diffs are sent to Cursor agent running locally
- **No External Services**: No data is sent to external servers (except Cursor's agent)

### Important Notes

⚠️ **Code Visibility**: When using Cursor agent, your code diff is processed by Cursor's AI models. Review Cursor's privacy policy for details.

🔒 **Sensitive Projects**: For highly sensitive codebases:
- Consider reviewing Cursor's data handling policies
- Use `DEEP_SKIP=1` to bypass reviews when needed
- Review generated `REVIEW_SUGGESTIONS.md` before committing

### Best Practices

- Review generated artifacts before committing them
- Use `.gitignore` to exclude `REVIEW_SUGGESTIONS.md` if it contains sensitive information
- Never commit API keys, tokens, or credentials (even in diffs)

## License

This project is licensed under the **MIT License**.


## Project Structure

```
deep_hook/
├── cli.py        # Commands
├── config.py     # YAML loading
├── git.py        # Diff extraction
├── reviewer.py   # Cursor integration
├── prompts.py    # AI prompts
├── formatter.py  # Terminal output
├── artifacts.py  # Markdown generation
└── models.py     # Data models
```

## Configuration Options

### `deep.yml` Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `base_branch` | string | `main` | Branch to compare against for diff |
| `language` | string | `python` | Project language (flutter, python, typescript, go, rust, other) |
| `timeout` | integer | `120` | Cursor agent timeout in seconds (10-600) |
| `max_diff_lines` | integer | `3000` | Maximum diff lines to review (100-10000) |
| `model` | string | `gpt-5.2-codex-fast` | Cursor agent model to use |
| `guidelines` | list | `[]` | Project-specific coding guidelines |

### Example Configuration

```yaml
base_branch: develop
language: flutter
timeout: 180
max_diff_lines: 5000
model: gpt-5.2-codex-fast
guidelines:
  - "Use BLoC pattern for state management"
  - "Prefer const constructors"
  - "No print() in production code"
```

## Documentation

- **[README.md](README.md)**: User guide and quick start
- **[TECHNICAL.md](TECHNICAL.md)**: Technical reference with imports and architecture
- **[CHANGELOG.md](CHANGELOG.md)**: Version history and changes
- **[LICENSE](LICENSE)**: MIT License

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes and version history.

## Support

- **Issues**: [GitHub Issues](https://github.com/anshd258/deep-hook/issues)
- **Documentation**: 
  - [README.md](README.md) - User guide
  - [TECHNICAL.md](TECHNICAL.md) - Developer documentation
  - [CHANGELOG.md](CHANGELOG.md) - Version history