BriefLook

See through any codebase in seconds.

BriefLook is a deterministic CLI that turns an unfamiliar repository into a compact map of its identity, setup, entry points, structure, and internal dependencies.

It runs locally and offline: no AI, no cloud service, and no repository upload. Results are based on repository evidence; unresolved information is not guessed.

Why BriefLook?

Before changing an unfamiliar repository, developers usually need to manually find:

• What kind of project is this?
• What is required to run it?
• Where should I start reading?
• Where does execution begin?
• How do internal packages connect, and are any circularly coupled?

BriefLook performs this initial inspection in one command.

Example

$ brieflook .

          Repository
+-----------------------------+
| Property        | Value     |
|-----------------+-----------|
| Name            | storefront|
| Language        | TypeScript|
| Framework       | React     |
+-----------------------------+

          Quick Start
+-----------------------------------------------+
| Prerequisite | Version | Reason               |
|--------------|---------|----------------------|
| Node.js      | >=20    | Defined in package…  |
+-----------------------------------------------+

                 Entry Points
+--------------------------------------------+
| # | Path               | Reason              |
|---|--------------------|---------------------|
| 1 | src/main.tsx       | React bootstrap.    |
+--------------------------------------------+

          Run Guide
+---------------------------+
| Step    | Command         |
|---------|-----------------|
| Install | npm install     |
| Run     | npm run dev     |
| Test    | npm test        |
+---------------------------+

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

      Module Dependencies
+-------------------------------+
| Package     | Depends On            |
|-------------|-----------------------|
| apps/web    | packages/ui           |
| apps/api    | packages/database     |
+-------------------------------+

      Circular Package Dependencies
+-------------------------------------------+
| Coupled Package Group                     |
|-------------------------------------------|
| packages/auth, packages/session           |
+-------------------------------------------+

The scan is intentionally compact: it highlights onboarding facts and proven relationships rather than printing every file import.

What BriefLook Tells You

Capability	Onboarding question it answers
Repository Identity	What project, language, framework, and package manager is this?
Quick Start	What prerequisites are needed?
Environment Setup	Which environment variables and setup files are present?
Start Here	Which documentation and configuration files should I read first?
Entry Points	Where can execution begin?
Run Guide	How can I install, run, and test the project?
Project Structure	Which directories make up the repository?
Workspace Detection	Which packages belong to an explicitly declared workspace?
Module Dependencies	Which internal architectural boundaries depend on others?
Circular Package Dependencies	Which package boundaries form a strongly connected group?

Install

pip install brieflook

Or install it as a uv tool:

uv tool install brieflook

Usage

# Scan the current directory
brieflook .

# Scan another repository
brieflook /path/to/repository

# Show the installed version
brieflook --version

What Is Currently Supported

BriefLook detects repository identity, prerequisites, environment setup, start-here files, entry points, run commands, project structure, explicit workspaces, and internal package dependencies.

Import intelligence currently supports Python, JavaScript, and TypeScript source files. It reports package-level relationships and compact circular package groups when repository evidence proves them.

Python Import Intelligence

For Python repositories, BriefLook analyzes imports using Python's AST and reports internal module relationships at package level. It supports absolute and relative imports, src/ layouts, and circular dependency detection.

External imports are not included in Module Dependencies.

JavaScript / TypeScript Import Intelligence

For JavaScript and TypeScript repositories, BriefLook supports:

• .js, .jsx, .ts, and .tsx files
• ES module imports, including default, named, namespace, and side-effect imports
• CommonJS require() and dynamic import()
• Relative imports, explicit extensions, and index.* resolution
• Explicit tsconfig.json and jsconfig.json path aliases

Only imports that resolve to actual repository files become internal graph relationships. External packages such as react, express, and axios are excluded. Unresolved imports are ignored rather than guessed.

BriefLook does not provide full TypeScript compiler semantics or bundler/plugin resolution.

Dependency Boundaries

Module Dependencies are aggregated at architectural boundaries, not arbitrary source folders.

• Declared workspace packages are the strongest boundary evidence.
• Nested package.json directories can establish independent package boundaries.
• Declared source roots from configuration, or a real src/ directory, can establish an application boundary.

Imports within the same boundary are omitted from the default table. For example, an import from src/pages/ to src/components/ does not create a pseudo-package dependency.

If BriefLook cannot establish a boundary from repository evidence, it prefers reporting fewer relationships over inventing one.

This keeps the default dependency view short enough to inspect in a normal terminal.

It also keeps raw file-level structure available in the repository rather than relabeling it as architecture.

The result is a compact starting point for repository onboarding.

Workspace and Monorepo Support

BriefLook recognizes explicitly declared workspaces from repository-root manifests for:

• pnpm
• npm, Yarn, and Bun
• uv
• Cargo
• Go

It only treats a repository as a workspace when that declaration is present at the root. Directories named apps/ or packages/ are not considered workspace packages by name alone.

Declared workspace packages can appear in Project Structure and act as dependency boundaries when imports actually connect them.

Evidence over Guessing

Repository evidence
        ↓
Deterministic analysis
        ↓
Reported result

BriefLook deliberately avoids:

• AI-generated architecture claims
• Guessed dependencies or invented entry points
• Treating arbitrary directories as workspaces or packages
• Cloud analysis and repository uploads

The goal is useful over impressive: show proven information, or show less.

Current Status

Current release: v0.3.0

v0.3.0 includes repository onboarding analysis, explicit workspace detection, Python and JavaScript/TypeScript ImportGraph support, package-level Module Dependencies, and SCC-based Circular Package Dependencies.

Roadmap

v0.4 — Application Surface Intelligence

• HTTP routes
• CLI commands
• Application-facing entry surfaces
• Relationships to internal modules

v0.5 — Public API Surface

• Public exports
• Exported modules
• Package exports
• Public interfaces

Future: Change & Impact Intelligence

If I change this module, what else could be affected?

The roadmap will evolve based on real developer feedback.

Feedback and Contributing

Scanned a repository and still had to manually search for something?

Tell us what BriefLook missed. Open a GitHub issue or discussion, ideally with this detail:

I scanned this repository, but I still had to manually search for ______.

BriefLook is intended as a fast first pass before making changes.

Use its output to focus your reading, then verify details in the repository itself.

It does not replace repository-specific review or engineering judgment.

To work on BriefLook locally:

git clone https://github.com/nabilkhan-01/brieflook.git
cd brieflook
uv sync
uv run brieflook .
uv run pytest

License

MIT License.