deep-hook 0.1.1

AI-powered Git pre-push code review using 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

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

Commands

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:

# 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

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 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:

   cursor --version
   cursor agent --help
   

Git Setup

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

git --version  # Should be 2.x or higher
git config --global user.name "Your Name"
git config --global user.email "[e-mail]"

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

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: User guide and quick start
• TECHNICAL.md: Technical reference with imports and architecture
• CHANGELOG.md: Version history and changes
• 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 for a detailed list of changes and version history.

Support

• Issues: GitHub Issues
• Documentation:
  • README.md - User guide
  • TECHNICAL.md - Developer documentation
  • CHANGELOG.md - Version history