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 or a remote Git URL. rebrief walks the stack, rules, git history, and risks, then writes REBRIEF.md.

---

🧭 Navigation

• 🎬 Demo
• 😫 The Pain
• ⚖️ Before vs. After
• ✨ Key Features
  • Stack detection
• 🚀 Installation & Quick Start
  • Status badges
  • JSON output
  • XML output
  • HTML output
  • Excluding paths with .rebriefignore
  • Remote repositories
  • Multi-repository system briefings
  • MCP server
  • Web UI
  • Chat mode
• 🐳 Docker
  • Air-gapped and CI usage
  • GitHub Actions with the container image
• ⚙️ GitHub Actions
  • Set up in your repository
  • Use on a pull request
• 📄 Example Output
• 💡 AI Prompting
• 📜 License

😫 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 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.
• Code Ownership & Expertise Map - Git blame analysis per module with contributor percentages, AI co-author detection (Claude, Cursor, Copilot, and similar), and expertise labels. Use --no-blame to skip on very large repositories.
• Local-First Risk Mapping - Static analysis for hardcoded secrets, unresolved technical debt (TODO/FIXME), missing test directories, and dependency conflicts. Secret-like values under test/fixture paths are reported as WARNING (confirm they are fixtures) rather than CRITICAL credentials to rotate. No cloud upload, no API keys.
• Token savings analysis - Estimates raw codebase tokens vs the generated brief (cl100k_base via optional tiktoken, or a len(text) / 4 fallback) and reports the compression ratio in the CLI, REBRIEF.md, JSON summary.token_stats, XML summary, and the HTML dashboard.
• Markdown, JSON, XML, or HTML output - Default handoff report is REBRIEF.md; use -f json for a structured REBRIEF.json payload, -f xml for a compact REBRIEF.xml brief, or -f html for a standalone REBRIEF.html dashboard.

Stack detection

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

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
pip install "rebrief[tokens]"   # optional: accurate cl100k_base token counts
pip install "rebrief[chat]"     # optional: rebrief chat (BYO LLM API key)

VS Code extension

Install the CLI first, then add the Rebrief extension from the Marketplace (or load rebrief-vscode/ in Extension Development Host). It adds a ⚡ Rebrief status bar action, an activity-bar sidebar, folder context-menu scans, and an in-editor HTML dashboard with one-click AI prompt copy.

cd rebrief-vscode
npm install
npm run compile

Settings: rebrief.executablePath, rebrief.format, rebrief.minConfidence, rebrief.autoScanOnSave.

rebrief scan .                      # TTY: settings panel, then start
rebrief scan . -y                   # skip the panel and scan immediately
rebrief scan . --plain              # no banner, color, or unicode
rebrief scan /path/to/repo -o REBRIEF.md
rebrief scan owner/repo             # GitHub shorthand → clone + scan
rebrief scan https://github.com/owner/repo
rebrief scan git@github.com:owner/repo.git
rebrief scan . -f json              # → REBRIEF.json
rebrief scan . -f json -o -         # JSON to stdout (status on stderr)
rebrief scan . -f xml               # → REBRIEF.xml
rebrief scan . -f xml -o -          # XML to stdout (status on stderr)
rebrief scan . -f html              # → REBRIEF.html
rebrief scan . -f html -o -         # HTML dashboard to stdout (status on stderr)
rebrief scan . --diff               # incremental vs HEAD~1
rebrief scan . --diff origin/main   # incremental vs PR/base ref
rebrief scan . --skip-vulnerability-check  # skip remote OSV CVE checks
rebrief scan . --no-blame                  # skip git blame ownership analysis
rebrief multi ./frontend ./backend         # unified system briefing → REBRIEF-SYSTEM.md
rebrief multi . -f json                    # → REBRIEF-SYSTEM.json
rebrief badge .                     # Shields.io Markdown + HTML to stdout
rebrief scan . --inject-badge       # update README.md badge markers
rebrief init .
rebrief mcp                         # MCP stdio server (requires rebrief[mcp])
rebrief mcp install                 # print IDE MCP config
rebrief serve                       # web UI at http://127.0.0.1:8000 (requires rebrief[web])
rebrief chat .                      # Q&A over REBRIEF.md (requires rebrief[chat])

Scan the current directory (default), any local path, or a remote Git repository (HTTPS, SSH, or GitHub owner/repo shorthand). Markdown output defaults to REBRIEF.md; JSON defaults to REBRIEF.json; XML defaults to REBRIEF.xml; HTML defaults to REBRIEF.html. Use -o to set a custom path, or -o - to write the report to stdout. Local scans write the report inside the target repo; remote scans write it in the directory where you ran the command.

Use --diff [REF] for an incremental scan of only files changed since a git ref (default HEAD~1). Stack, risk, and hotspot analysis run against that file list; structural checks such as a tests/ directory remain repo-wide. Incremental Markdown reports are titled REBRIEF INCREMENTAL REPORT, and JSON includes "mode": "incremental", "diff_ref", plus summary.files_scanned / summary.files_total.

Status badges

Generate a Shields.io badge from the current scan results:

rebrief badge .

Prints Markdown and HTML snippets to stdout. Colors reflect confidence-filtered risks: brightgreen (clean), yellow (N risks when only warnings/info), or red (N critical).

To keep a live badge in your README, add marker comments (or let --inject-badge create them):

<!-- REBRIEF-BADGE:START -->
[![Rebrief](https://img.shields.io/badge/rebrief-clean-brightgreen)](https://github.com/neracu/rebrief)
<!-- REBRIEF-BADGE:END -->

rebrief scan . --inject-badge

If the markers are present, the content between them is replaced. If they are missing, the badge block is inserted under the primary # Header in README.md.

JSON output

For automation or downstream tools, pass -f json (or --format json). The report is a typed JSON object with mode, diff_ref, summary, tech_stack, timeline, ownership_map, risk_map, and checklist — the same analysis as the Markdown report, without section prose. The summary object includes badge_url, badge_markdown, file-count fields (files_scanned, files_total), token_stats (raw_codebase_tokens, brief_tokens, savings_percentage, tokenizer), and doc_drift (freshness_score, freshness_label, scanned_files, components, items) for documentation freshness analysis.

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.

XML output

For Claude and other LLM context windows, pass -f xml (or --format xml). The report is a compact, indented XML projection of the same analysis: summary, tech_stack, hotspots, risk_map, and checklist. Risks are a flat list with severity and confidence attributes. Token savings live under summary as raw_tokens, brief_tokens, and savings_percentage. The root version attribute matches the installed package version.

XML omits verbose JSON-only fields (commit timeline, dependency lists, badges, tokenizer metadata) so the file stays small enough to paste into a prompt.

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

<?xml version="1.0" encoding="UTF-8"?>
<rebrief version="0.3.0">
  <summary>
    <languages_count>2</languages_count>
    <risks_count>2</risks_count>
    <raw_tokens>45200</raw_tokens>
    <brief_tokens>850</brief_tokens>
    <savings_percentage>98.12</savings_percentage>
  </summary>
  <tech_stack>
    <languages>
      <language>JavaScript/TypeScript</language>
      <language>Python</language>
    </languages>
    ...
  </tech_stack>
  ...
</rebrief>

HTML output

For an interactive, offline dashboard, pass -f html (or --format html). The report is a single self-contained REBRIEF.html file with inline CSS and vanilla JavaScript — no CDN, no local web server. Open it in any browser to filter the risk matrix, search file paths, sort churn hotspots, switch to a raw Markdown view, and copy a pre-formatted AI prompt to the clipboard.

GitHub Actions and rebrief.ci.comment still expect Markdown (REBRIEF.md); use HTML locally for exploration.

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

Excluding paths with .rebriefignore

rebrief skips common noise by default (node_modules, .git, dist, build, .next, .rebrief, __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 of a local directory, rebrief creates .rebriefignore automatically if it is missing. Patterns in that file supplement the built-in defaults — they do not replace them.

Remote repositories

rebrief scan accepts a Git URL or GitHub shorthand and shallow-clones into a temporary directory (git clone --depth 100 --single-branch), then deletes the clone when the scan finishes.

rebrief scan owner/repo
rebrief scan https://github.com/owner/repo
rebrief scan https://gitlab.com/group/repo
rebrief scan git@github.com:owner/repo.git

owner/repo resolves to https://github.com/owner/repo. If that path already exists as a local directory, rebrief scans the directory instead of cloning.

Private repositories use your local Git credentials (SSH keys, gh auth, credential helpers). You can also set GITHUB_TOKEN or GIT_AUTH_TOKEN for HTTPS clones. If the clone fails, rebrief exits with:

Error: Unable to access remote repository. Check the URL or your Git authentication credentials.

Multi-repository system briefings

Combine multiple linked codebases (frontend + backend + infra) or monorepo workspace packages into one unified architecture briefing:

rebrief multi ./frontend ./backend
rebrief multi ./frontend https://github.com/org/backend
rebrief multi .                              # auto-expand pnpm/lerna/npm/Cargo workspaces
rebrief multi ./apps/web ./apps/api -f json  # → REBRIEF-SYSTEM.json
rebrief multi ./frontend ./backend -o -      # Markdown to stdout (status on stderr)

rebrief multi accepts any mix of local paths and remote Git URLs (HTTPS, SSH, or GitHub owner/repo shorthand). When a target root contains pnpm-workspace.yaml, lerna.json, npm workspaces, or a Cargo [workspace], rebrief expands it into member packages automatically.

The default output is REBRIEF-SYSTEM.md in the directory where you ran the command. JSON (-f json) writes REBRIEF-SYSTEM.json; XML (-f xml) writes REBRIEF-SYSTEM.xml.

The system report includes:

• System architecture summary — aggregated tiers (Frontend / Backend / Infra / Shared) across all services
• Cross-repo hotspot matrix — ranked churn across packages
• Unified risk map — merged critical items, warnings, and vulnerabilities with [service] prefixes
• Shared dependency graph — duplicated or version-mismatched dependencies across packages
• Per-service sections — condensed stack, hotspots, and risks for each scanned member

Use the same confidence, vulnerability, and blame flags as rebrief scan (-c, --skip-vulnerability-check, --no-blame).

MCP server

AI agents (Claude Code, Cursor, Windsurf, Roo Code) can query stack, risks, hotspots, and the full REBRIEF.md summary over Model Context Protocol stdio.

pip install "rebrief[mcp]"
rebrief mcp            # start the stdio server
rebrief server         # alias for `rebrief mcp`
rebrief mcp install    # print client JSON (add --write to merge into config files)

If the extra is not installed, rebrief mcp exits with install instructions. Repeated tool calls in one agent session are served from an in-memory cache plus .rebrief/cache.json (file fingerprint), so unchanged local repos skip a rescan. Remote URL targets are cloned on demand and cached in memory for the server process (force_refresh re-clones).

Tools: get_repository_brief, get_risk_map, get_codebase_hotspots, get_tech_stack

Each tool takes path, which may be a local directory, an HTTPS/SSH git URL, or GitHub owner/repo shorthand.

Resource: rebrief://summary — latest markdown brief for the working directory

Prompt: rebrief_context — pre-packaged instruction that injects the Rebrief summary

Cursor / Windsurf snippet (.cursor/mcp.json or mcp.json):

{
  "mcpServers": {
    "rebrief": {
      "command": "rebrief",
      "args": ["mcp"]
    }
  }
}

Claude Code:

claude mcp add rebrief -- rebrief mcp

rebrief mcp install --write merges that entry into Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), Roo (.roo/mcp.json), and Claude Desktop (claude_desktop_config.json) without removing other servers.

Web UI

Paste a public GitHub, GitLab, or Bitbucket URL and view REBRIEF.md in the browser. No Node, Docker, or extra processes.

pip install "rebrief[web,tokens]"
rebrief serve

That starts the API and UI together at http://127.0.0.1:8000/ and opens it in your default browser. Use --no-open to skip the browser, or --port 8000 to change the port.

POST /api/scan accepts { "url", "min_confidence", "diff_ref" }, shallow-clones (--depth 50), and returns markdown, token stats, tech stack, and risk counts. Repeat requests for the same repo_url:commit_sha are served from cache. Rate limit: 10 scans per minute per IP.

POST /api/chat streams Server-Sent Events for repo Q&A. Body: { "repo_url", "messages", "api_key?", "model?" }. The handler reuses the scan cache for REBRIEF context, injects the system prompt server-side, and proxies the model with a BYO key (or server env vars). API keys are never written to cache, logs, or disk. Rate limit: 20 chat requests per minute per IP (CHAT_RATE_LIMIT).

Split deploy (optional): run rebrief serve on the API host (or pip install "rebrief[web,tokens]"); Vercel project root web/ with NEXT_PUBLIC_API_URL pointing at the API origin. For CI and air-gapped scans, use the official Docker image instead.

Chat mode

Ask questions about a scanned repository using the REBRIEF context window and your own LLM API key.

pip install "rebrief[chat,tokens]"
export OPENAI_API_KEY=sk-...          # or ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY / OLLAMA_BASE_URL
# or put the same variables in a .env file in the working directory
rebrief chat .                        # load REBRIEF.md/json if present, otherwise scan
rebrief chat . --file REBRIEF.md
rebrief chat owner/repo -m anthropic/claude-3-5-sonnet
rebrief chat . -m openrouter/openai/gpt-4o-mini
rebrief chat . -m ollama/llama3       # local OpenAI-compatible endpoint

Default model is the first available provider: anthropic/claude-3-5-sonnet, openai/gpt-4o-mini, gemini/gemini-2.0-flash, openrouter/openai/gpt-4o-mini, then ollama/llama3. Pass --key to override the environment. rebrief chat and rebrief serve also read a .env file from the working directory (existing process env vars win). Keys are never written to disk.

REPL slash commands: /clear (reset memory), /copy (clipboard last reply), /context (token usage), /exit or /quit.

---

🐳 Docker

Official multi-arch images are published to GitHub Container Registry on every v* release tag:

ghcr.io/neracu/rebrief:latest · ghcr.io/neracu/rebrief:v0.3.0

The image is a minimal CLI runtime (python:3.12-slim, git, ca-certificates) with ENTRYPOINT ["rebrief"] and default CMD ["scan", "."]. It runs as UID 1000 (non-root) and does not bundle the Next.js web UI.

Air-gapped and CI usage

Pull once on a runner or mirror, then scan a mounted workspace without installing Python or PyPI packages:

docker pull ghcr.io/neracu/rebrief:latest

docker run --rm \
  -v "$(pwd):/app" \
  -w /app \
  ghcr.io/neracu/rebrief:latest \
  scan . -f json -o REBRIEF.json --skip-vulnerability-check

Mount the repository at /app (or any path) and set -w to that directory. Use --skip-vulnerability-check when outbound OSV API access is blocked. Output files must be writable by UID 1000 inside the container (world-writable dirs or matching ownership).

Other subcommands work the same way:

docker run --rm -v "$(pwd):/app" -w /app ghcr.io/neracu/rebrief:latest init .
docker run --rm ghcr.io/neracu/rebrief:latest --version

GitHub Actions with the container image

docker run step (works on any runner with Docker):

- uses: actions/checkout@v4

- name: Scan with rebrief container
  run: |
    docker run --rm \
      -v "${{ github.workspace }}:/app" \
      -w /app \
      ghcr.io/neracu/rebrief:latest \
      scan . -f json -o REBRIEF.json --skip-vulnerability-check

Container job (checkout lands in /github/workspace):

jobs:
  scan:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/neracu/rebrief:latest
    steps:
      - uses: actions/checkout@v4
      - run: rebrief scan . -f json -o REBRIEF.json --skip-vulnerability-check

docker:// action step (GitHub mounts the workspace at /github/workspace):

- uses: actions/checkout@v4

- uses: docker://ghcr.io/neracu/rebrief:latest
  with:
    args: scan /github/workspace -f json -o /github/workspace/REBRIEF.json --skip-vulnerability-check

---

⚙️ 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.
- Project context 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

### 👥 Code Ownership & Expertise Map
| Module / Path | Primary Owner | Secondary / AI Contributor | Expertise Level |
|---|---|---|---|
| `apps/backend/` | Alex (65%) | 🤖 AI-Assisted (35% Claude) | High Activity |
| `packages/db/` | Aidar (80%) | Alice (20%) | Stable / Maintenance |

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

## 6. 📉 Documentation Freshness & Drift
Freshness Score: 72% (Needs Review)
- [WARNING] [Confidence: HIGH] README.md references "Vue" but project depends on "React"
- [WARNING] [Confidence: MEDIUM] `.env.example` defines `API_KEY` but it is not documented in project docs

## 7. 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).

> 💡 **Token Savings:** `REBRIEF.md` uses **850 tokens** instead of **45.2k raw tokens** (**98.1% reduction**).

---

💡 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.

With MCP enabled, bind the rebrief://summary resource or run the rebrief_context prompt so the model receives the latest architectural hotspots and risks without a manual file read.

Or run rebrief chat . to ask questions in the terminal against the same REBRIEF context window.

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