Metadata-Version: 2.4
Name: deep-hook
Version: 0.1.0
Summary: AI-powered Git pre-push code review using Cursor
Home-page: https://github.com/anshd258/deep-hook
Author: anshdeep
License: MIT
Project-URL: Homepage, https://github.com/anshd258/deep-hook
Project-URL: Repository, https://github.com/anshd258/deep-hook
Project-URL: Issues, https://github.com/anshd258/deep-hook/issues
Keywords: git,code-review,ai,pre-push,hook,cursor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: gitpython>=3.1
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🔗 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

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

For detailed technical documentation, see [TECHNICAL.md](TECHNICAL.md).

## Contributing

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

## Support

- **Issues**: [GitHub Issues](https://github.com/anshd258/deep-hook/issues)
- **Documentation**: See [TECHNICAL.md](TECHNICAL.md) for developer docs
