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

Before	After
A week manually digging through code	A 30-second local scan
Guessing project boundaries and setup context	Harvested context from rules files and README
Noisy git history hiding real decisions	Filtered timeline + churn hotspots
Unknown security and test gaps	Prioritized risk map + developer checklist

rebrief scan .
# → REBRIEF.md

---

Key Features

• Deep Stack & Manifest Detection - Recursive scan for ecosystem manifests across JavaScript/TypeScript, Python, Go, Rust, Java, Kotlin, PHP, and Ruby — including mono-repos and nested layouts. Parses dependencies, infers frameworks, and flags malformed manifests as warnings.
• 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.
• Markdown or JSON output - Default handoff report is REBRIEF.md; use -f json for a structured REBRIEF.json payload (stack, timeline, risks, checklist) for scripts and tooling.

Stack detection

rebrief walks the repo (up to three directory levels) and looks for common manifest files:

Ecosystem	Manifests	Framework signals
JavaScript / TypeScript	package.json	React (react), Next.js (next, next.config.js / .mjs), Vue (vue), Angular (@angular/core, angular.json), Svelte (svelte, svelte.config.js), Express (express), NestJS (@nestjs/core), Remix (@remix-run/node, remix.config.js), Vite (vite.config.js / .ts), Nuxt.js (nuxt.config.js / .ts)
Python	requirements.txt, pyproject.toml, poetry.lock	Django (django, manage.py), Django REST Framework (djangorestframework), FastAPI (fastapi), Flask (flask)
Go	go.mod	Gin (gin-gonic/gin), Echo (labstack/echo), Fiber (gofiber/fiber)
Rust	Cargo.toml	Actix Web (actix-web), Axum (axum), Rocket (rocket)
Java	pom.xml, build.gradle	Spring Boot (spring-boot), Quarkus (quarkus), Micronaut (micronaut)
Kotlin	build.gradle.kts	Spring Boot (spring-boot), Quarkus (quarkus), Micronaut (micronaut)
PHP	composer.json	Laravel (laravel/framework, artisan), Symfony (symfony/framework-bundle), Slim (slim/slim)
Ruby	Gemfile	Rails (rails), Sinatra (sinatra)

Each parser extracts direct dependencies from the manifest (for example require lines in go.mod, [dependencies] in Cargo.toml, or require in composer.json). Dependency-based framework detection uses exact matching for simple package names and substring matching for module coordinates (Go import paths, Maven/Gradle coordinates, Composer packages). Signature files such as manage.py, artisan, and angular.json are detected by filename alone.

If a manifest cannot be parsed, the scan continues and the report lists a WARNING for that file instead of failing the whole run.

---

Installation & Quick Start

pip install rebrief

rebrief scan .
rebrief scan /path/to/repo -o REBRIEF.md
rebrief scan . -f json              # → REBRIEF.json
rebrief scan . -f json -o -         # JSON to stdout (status on stderr)
rebrief init .

Scan the current directory (default) or any local path. Markdown output defaults to REBRIEF.md; JSON defaults to REBRIEF.json. Use -o to set a custom path, or -o - to write the report to stdout.

JSON output

For automation or downstream tools, pass -f json (or --format json). The report is a typed JSON object with summary, tech_stack, timeline, risk_map, and checklist — the same analysis as the Markdown report, without section prose.

rebrief scan . -f json
rebrief scan . -f json -o report.json
rebrief scan . -f json -o - > REBRIEF.json

The version field matches the installed rebrief package version. GitHub Actions and rebrief.ci.comment still expect Markdown (REBRIEF.md); use JSON locally or in custom pipelines.

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