debrief: Project Summarizer
debrief generates a comprehensive BRIEF.md file designed to provide new contributors or coding agents with a high-density overview of a Python project.
Installation
pip install debrief
Usage
debrief [run|lint] [path] [--output BRIEF.md]
Arguments
| Argument | Description | Default |
|---|---|---|
mode |
run generates BRIEF.md, lint only runs checks. |
run |
path |
Project root path. | . |
-o, --output |
Output filename. | BRIEF.md |
--tree-budget |
Max lines for Directory Tree (auto-depth). | 60 |
--max-tree-siblings |
Max items at same level in tree. | tree_budget/3 |
--max-readme |
Max lines to include from README. | 20 |
--max-deps |
Max lines for dependencies list. | 15 |
--max-imports |
Max lines for Import Tree. | 50 |
--max-definitions |
Max lines for Module Definitions. | 200 |
--max-class-methods |
Max public methods shown per class. | max_definitions/3 |
--max-module-defs |
Max top-level defs shown per module. | max_definitions/3 |
--include-docstrings |
Include docstrings in the output. | False |
--exclude |
Additional patterns to exclude. | None |
Lint Mode
debrief lint [path]
Runs all quality checks without generating BRIEF.md:
| Check | Threshold | Condition |
|---|---|---|
| README non-empty lines | ≥ 2 | Always |
| Description length | ≥ 16 non-ws chars | Always |
| Docstring length | ≥ 16 non-ws chars | Only with --include-docstrings |
Features
- Project Metadata: Extracts description and dependencies from
pyproject.toml(withrequirements.txtfallback). - Directory Tree: Adaptive depth tree that fits within a line budget, respecting
.gitignore. - Import Analysis: Generates an import dependency tree to visualize project structure.
- Code Definitions: Extracts class and function signatures with docstrings for all Python files.
- Optimized Output:
- Truncation: Automatically truncates long lines (>300 chars) and large sections.
- "Read more": Links to local files for truncated content.
- Markdown: Formatted for optimal readability.
Example Output (BRIEF.md)
The BRIEF.md file in this repository serves as a real example of the output of debrief.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
debrief-0.8.6.tar.gz
(18.3 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
debrief-0.8.6-py3-none-any.whl
(13.7 kB
view details)
File details
Details for the file debrief-0.8.6.tar.gz.
File metadata
- Download URL: debrief-0.8.6.tar.gz
- Upload date:
- Size: 18.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0510b162449f57098fa808374f712ae586eeb4c972e4a5bf790b402e17587c18
|
|
| MD5 |
6b4c581e5bdcc93952035764743d524c
|
|
| BLAKE2b-256 |
dcfb04147409b235c6d64736d3489c0bc93b69cc3f8119d4ec82959b0b3bf05e
|
File details
Details for the file debrief-0.8.6-py3-none-any.whl.
File metadata
- Download URL: debrief-0.8.6-py3-none-any.whl
- Upload date:
- Size: 13.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
80e34957f13f823e99cdebda9fd983beaf6346074cec57279dea96b167a493df
|
|
| MD5 |
cd6989601a05af1b58e1ae516bb7548b
|
|
| BLAKE2b-256 |
b7d6481b0864c0af7fa19fbcc67bfacfc5c7103e801f36bc7000adab47ddafd5
|
