BriefLook

See through any codebase in seconds.

Built for developers joining unfamiliar repositories.

BriefLook is a deterministic repository X-ray CLI that answers the core onboarding questions developers ask when opening a new project. It analyzes explicit repository evidence to produce fast, repeatable results—completely offline, without AI, and without guesswork.

Why BriefLook?

Understanding an unfamiliar codebase often takes longer than writing code.

Developers typically switch between documentation, project configuration, source files, and other tools to answer basic onboarding questions:

• What kind of project is this?
• What do I need before it will run?
• Where should I start reading?
• Where does execution begin?
• How do I build, run, and test it?

BriefLook answers these questions by analyzing repository evidence directly—from project configuration, lockfiles, container specifications, and source structure.

Every reported fact is traceable to a repository artifact. If BriefLook cannot prove something from the repository, it does not report it.

Key Features

Output Example

Run BriefLook on any local repository:

brieflook .

          Repository           
+-----------------------------+
| Property        | Value     |
|-----------------+-----------|
| Name            | BRIEFLOOK |
| Language        | Python    |
| Framework       | Typer CLI |
| Package Manager | uv        |
| Project Type    | CLI Tool  |
+-----------------------------+

                     Quick Start                      
+----------------------------------------------------+
| Prerequisite | Version | Reason                    |
|--------------+---------+---------------------------|
| Python       | >=3.11  | Defined in pyproject.toml |
+----------------------------------------------------+

                                  Start Here                                   
+-----------------------------------------------------------------------------+
| # | Path                      | Reason                                      |
|---+---------------------------+---------------------------------------------|
| 1 | README.md                 | Repository documentation                    |
| 2 | src/brieflook/__main__.py | Entry point for this cli tool.              |
| 3 | pyproject.toml            | Defines dependencies for this project,      |
|   |                           | managed with uv.                            |
+-----------------------------------------------------------------------------+

                         Entry Points                          
+-------------------------------------------------------------+
| # | Path                      | Reason                      |
|---+---------------------------+-----------------------------|
| 1 | src/brieflook/__main__.py | Python package entry point. |
+-------------------------------------------------------------+

          Run Guide           
+----------------------------+
| Step    | Command          |
|---------+------------------|
| Install | uv sync          |
| Run     | uv run brieflook |
| Test    | pytest           |
+----------------------------+

             Project Structure             
+-----------------------------------------+
| # | Directory | Purpose                 |
|---+-----------+-------------------------|
| 1 | src/      | Application source code |
| 2 | tests/    | Project tests           |
+-----------------------------------------+

Product Philosophy

1. One Onboarding Question per Feature: Every feature exists to answer exactly one real onboarding question and save meaningful developer time.
2. Evidence over Guessing: Every output fact is backed by explicit repository evidence (config files, lockfiles, container specs). No heuristics, no guessing.
3. Deterministic Analysis: Fast, offline, static analysis with zero AI hallucination.
4. Explicit Evidence: Every reported fact can be traced back to a specific repository artifact. If BriefLook cannot prove something, it does not report it.

Installation & Usage

For Users

Install via uv or pip:

uv tool install brieflook
# or
pip install brieflook

Run BriefLook on any target repository:

brieflook /path/to/repository

For Contributors

Clone the repository and set up a local development environment:

git clone https://github.com/nabilkhan-01/brieflook.git
cd brieflook

uv sync
uv run brieflook .

License

MIT