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
Metadata
1 maintainer
Release files for debrief 0.8.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| debrief-0.8.6.tar.gz | 18.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| debrief-0.8.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 32.0 kB
Release files / debrief-0.8.6.tar.gz
| Download URL | debrief-0.8.6.tar.gz |
|---|---|
| Size | 18.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0510b162449f57098fa808374f712ae586eeb4c972e4a5bf790b402e17587c18
|
|
BLAKE2b-256 checksum How to use checksums |
dcfb04147409b235c6d64736d3489c0bc93b69cc3f8119d4ec82959b0b3bf05e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is 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}
|
Release files / debrief-0.8.6-py3-none-any.whl
| Download URL | debrief-0.8.6-py3-none-any.whl |
|---|---|
| Size | 13.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
80e34957f13f823e99cdebda9fd983beaf6346074cec57279dea96b167a493df
|
|
BLAKE2b-256 checksum How to use checksums |
b7d6481b0864c0af7fa19fbcc67bfacfc5c7103e801f36bc7000adab47ddafd5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is 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}
|
