---
slug: "bruhook"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/geakstr/bruhook@main/README.md"
repo: "https://github.com/geakstr/bruhook"
source_file: "README.md"
branch: "main"
---
# bruhook

A buddy system for Claude Code that watches your back during long coding sessions.

## The problem

If you've used Claude Code for anything beyond quick fixes, you've probably hit these:

**Context evaporates.** You step away, come back, resume the session... and Claude has no idea what was happening. You spend 10 minutes re-explaining the plan.

**The plan drifts.** You start with a clear plan, Claude gets excited, and suddenly it's refactoring half the codebase because "it seemed like a good opportunity."

**"I'm done!" (but not really).** Claude confidently claims the task is complete. You check the plan - three steps are missing. Classic.

**No breadcrumbs.** Something went sideways mid-session, but there's no record of what happened or why.

## What bruhook does

It's a set of hooks that plug into Claude Code and run automatically:

- **Code reviewer** - Every time a file changes, a background Claude session checks if it matches the plan. Drift gets logged.
- **Plan tracker** - Maps your session to its plan file so other hooks can find it.
- **Context restorer** - When you resume a session or it gets compacted, bruhook injects the plan and review log back in.
- **Completion checker** - When Claude tries to stop, bruhook checks if the plan is actually done. If not, it blocks the stop and tells Claude what's missing.

## Installation

Install bruhook as a Claude Code plugin:

```text
/plugin install github:geakstr/bruhook
```

## Usage

1. Enable bruhook when you want it active:

    ```bash
    export BRUHOOK_ENABLED=true
    ```

2. Start a Claude session and create a plan (Claude usually puts these in `~/.claude/plans/`)

3. Work normally - bruhook tracks everything in the background

4. Review logs are created in your project directory at `.bruhook/reviews/`

5. Resume anytime with `/resume` - context gets restored automatically

## Commands

| Command | Description |
| --------- | ------------- |
| `/bruhook:status` | Show tracking status for current session |
| `/bruhook:log` | View the review log for current session |

## Config

| Variable | What it does |
| ---------- | -------------- |
| `BRUHOOK_ENABLED` | Set to `true` to activate review and completion hooks |
| `BRUHOOK_PLAN_PATH` | Override the plan file path (optional) |
| `CLAUDE_PROJECT_DIR` | Set automatically by Claude Code to your project directory |

The plan tracker hook always runs (so it can map sessions to plans). The other hooks only kick in when `BRUHOOK_ENABLED=true`.

## Requirements

- Bash 4.0+
- `jq` for JSON parsing
- `git` for diff checking
- Claude Code with plugin support

## How it's built

~500 lines of bash. Hook scripts in `scripts/` share a helper (`lib/resolve-plan.sh`) for finding plan files. The plugin manifest and hooks configuration handle routing.

## Future work

**Faster reviews.** Currently the code reviewer checks the entire file against the plan on every edit. A better approach would be shallow reviews based on just the diff of the latest change.