rebrief

Instantly turn any unfamiliar repository into a clean developer handoff dossier.

A local CLI that scans any codebase and produces a structured REBRIEF.md report in ~30 seconds - stack, context, history, risks, and a where-to-start checklist.

Demo

rebrief scan .

Point it at any local repo. rebrief walks the stack, rules, git history, and risks, then writes REBRIEF.md in the project root.

The Pain

You join a new project - after an outsourcing handoff, a freelancer exit, or years of legacy development. Your first week disappears into onboarding archaeology: manually mapping the tech stack, hunting buried TODOs, sorting through a noisy Git history, and trying to spot security and test gaps before you can ship anything. The knowledge is in the repo; nobody assembled it.

Before vs. After

rebrief scan .
# → REBRIEF.md

Key Features

• Deep Stack & Manifest Detection - Recursive scan for package.json, pyproject.toml, go.mod, Cargo.toml, and more. Detects languages and frameworks (Django, React, Next.js, Go, and others) across mono-repos and nested layouts.
• Context & Rules Harvesting - Extracts local project context from .cursorrules, CLAUDE.md, README.md, and related instruction files so the next developer knows how the project was meant to be built.
• Noise-Filtered Git Archaeology - Filters low-value commits (wip, fix typo, minor updates) to surface a cleaner timeline of meaningful changes and 30-day change-density hotspots.
• Local-First Risk Mapping - Static analysis for hardcoded secrets, unresolved technical debt (TODO/FIXME), missing test directories, and dependency conflicts. No cloud upload, no API keys.

Installation & Quick Start

pip install rebrief

rebrief scan .
rebrief scan /path/to/repo -o REBRIEF.md
rebrief init .

Scan the current directory (default) or any local path. Output defaults to REBRIEF.md in the target repo.

Excluding paths with .rebriefignore

rebrief skips common noise by default (node_modules, .git, dist, build, .next, __pycache__, .venv, and similar). To exclude more paths, add a .rebriefignore file at the repo root using standard .gitignore syntax (globs, # comments, one pattern per line).

rebrief init .   # create a starter .rebriefignore

On the first rebrief scan, rebrief creates .rebriefignore automatically if it is missing. Patterns in that file supplement the built-in defaults — they do not replace them.

GitHub Actions

Run rebrief scan on pull requests and post a summarized risk report as a PR comment.

Set up in your repository

Copy these files from this repo into yours:

.github/workflows/rebrief-ci.yml
.github/actions/rebrief-action/

In consumer repos, do not set use-local-package: true — the action installs rebrief from PyPI. That option is only for development in this repository.

Use on a pull request

1. Open a PR (not a draft).
2. Add the rebrief label to the PR.
3. The workflow runs and posts (or updates) a comment on the PR with the scan summary.

Re-runs on new commits update the same comment instead of creating duplicates.

In this repository, the workflow is label-gated — add rebrief to trigger it. See .github/actions/rebrief-action/README.md for all inputs and workflow variants.

name: rebrief

on:
  pull_request:
    types: [opened, synchronize, reopened, labeled]

permissions:
  contents: read
  pull-requests: write

jobs:
  scan:
    if: contains(github.event.pull_request.labels.*.name, 'rebrief')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # required for git timeline and hotspots

      - uses: ./.github/actions/rebrief-action
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          only-on-risk: false
          skip-drafts: true

Set only-on-risk: true to post comments only when WARNING or CRITICAL risks are found.

Example Output

# REBRIEF REPORT: my-app

## 1. Project Overview (Executive Summary)
- This repository uses 1 language(s) and has 4 risk item(s) that need developer attention.
- AI instruction files found: 2 (.cursorrules, CLAUDE.md).
  - `.cursorrules`: 12 lines
  - `CLAUDE.md`: 5 lines

## 2. Technology Stack and Dependencies
- **Languages:** Python
- **Frameworks:** Django
- **Manifests:** pyproject.toml
- **Key dependencies:**
  - `click>=8.1`
  - `django==4.2`

## 3. Solution Timeline (Git History)
- `a1b2c3d` (2026-01-15) Add authentication module — Alice

### Hotspots (Change Density)
- src/app.py: 8 changes

## 4. Risk Map (AI Debt & Security)
### [CRITICAL]
- Hard-coded secret in config.py:3

### [WARNING]
- Missing tests directory (`tests/`, `test/`, or `__tests__/`).
- Duplicate dependency `django` with conflicting versions: ==3.2, ==4.2.

### [INFO]
- TODO in app.py:10

## 5. Developer Checklist ("Where to Start")
1. Review and rotate hard-coded credentials in config.py (line 3).
2. Add a `tests/` directory and cover critical paths.
3. Resolve version conflict for `django`: ==3.2, ==4.2.
4. Set up the development environment for Django.
5. Review frequently changed file: src/app.py (8 edits in 30 days).

AI Prompting

After generating REBRIEF.md, point your AI assistant at it before diving into the codebase. In Cursor or Claude, use this prompt:

Read REBRIEF.md before starting to understand the project's architecture and hotspots.

This gives the model a structured overview of the stack, risks, and where to start - so you spend less time re-explaining the repo on every session.

License

MIT