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, internal dependencies, application assembly, and change impact.

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 answer two key questions:

1. brieflook . — "How is this repository organized?" Highlights language, framework, prerequisites, entry points, project structure, package dependencies, and container assembly.

2. brieflook impact <path> — "What could be affected if I change this?" Surfaces direct and transitive internal dependents derived from import relationships.

Examples

1. Repository Scan (brieflook .)

$ 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 | pnpm install    |
| Run     | pnpm dev        |
| Test    | pnpm test       |
+---------------------------+

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

     Application Assembly
+-----------------------------------------+
| Component | Kind    | Ports | Depends On|
|-----------+---------+-------+-----------|
| api       | compose | 8080  | db        |
| db        | compose | 5432  | -         |
+-----------------------------------------+

2. Change & Impact Analysis (brieflook impact <path>)

$ brieflook impact src/core/engine.py --include-tests

             Potential Impact
+----------------------------------------+
| Property | Value                       |
|----------+-----------------------------|
| Target   | src/core/engine.py          |
+----------------------------------------+

Direct Dependents
  src/api/routes.py
  src/cli/main.py

Transitive Dependents
  src/app.py

Test Impact
  tests/test_engine.py

What BriefLook Tells You

Capability	Onboarding / Change-management 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?
Application Assembly	How do services, ports, and containers assemble from Compose/Docker declarations?
Change & Impact Intelligence	What files may be affected by changing this file or directory based on import relationships?

Install

pip install brieflook

Or install as a uv tool:

uv tool install brieflook

Usage

# Scan repository organization
brieflook .
brieflook /path/to/repository

# Analyze potential change impact
brieflook impact src/brieflook/core/index.py
brieflook impact src/brieflook/core/index.py --include-tests
brieflook impact D:\path\to\repository\src\some_file.py

# Show installed version
brieflook --version

Change & Impact Intelligence

brieflook impact <path> answers: "If I change this file or directory, which other files could be affected?"

• Evidence-based: Reports potential impact derived strictly from repository import relationships. It does not predict guaranteed breakage, semantic failure, or runtime bugs.
• Direct & Transitive: Surfaces direct dependents (modules that import the target) and transitive dependents (modules that import direct dependents).
• Test Impact: Separates production code from test files. Use --include-tests to show test dependents.
• Circular Groups: Displays a warning if the target module belongs to a circular dependency group.
• Target Resolution: Supports repository-relative paths (src/foo.py, src\foo.py) and absolute paths (D:\path\to\repo\src\foo.py).

Application Assembly

BriefLook analyzes explicitly declared Docker Compose (compose.yaml, docker-compose.yml) and Dockerfile configuration to surface multi-container deployment architecture:

• Compose Analysis: Detects services, image, build context, host/container ports, service relationships (depends_on), command/entrypoint, environment variable names, and env_file.
• Dockerfile Analysis: Detects base images (FROM), exposed ports (EXPOSE), CMD, and ENTRYPOINT.
• Run Guide Integration: Adds docker compose up to the Run Guide when root Compose declarations exist.

Note: BriefLook reports declared repository assembly evidence. It does not inspect runtime container state, Kubernetes clusters, live health, port conflicts, or runtime variable values.

Import Intelligence (Python, JS/TS)

BriefLook builds a language-agnostic ImportGraph for Python and JavaScript/TypeScript:

• Python: Analyzes imports using Python's AST. Supports absolute and relative imports, src/ layouts, and package aggregation.
• JavaScript & TypeScript: Supports .js, .jsx, .ts, .tsx, ES imports, CommonJS require(), dynamic import(), relative paths, index.* resolution, and tsconfig.json/jsconfig.json path aliases.

External dependencies (e.g., react, express, pytest) are excluded. Unresolved imports are ignored rather than guessed.

Dependency Boundaries

Module Dependencies are aggregated at architectural boundaries rather than arbitrary source folders:

• Declared workspace packages are the strongest boundary evidence.
• Nested package.json directories can establish independent package boundaries.
• Declared source roots (or a real src/ directory) establish application boundaries.
• Imports within the same boundary are omitted from package dependency tables to avoid clutter.

Workspace and Monorepo Support

BriefLook recognizes explicitly declared workspaces from repository-root manifests for pnpm, npm, Yarn, Bun, uv, Cargo, and Go. Workspaces are recognized only when declarations exist at the root.

Evidence over Guessing

Repository evidence
        ↓
Deterministic analysis
        ↓
Reported result

BriefLook avoids AI-generated claims, guessed dependencies, and cloud uploads. The core principle is useful over impressive: show proven information, or show less.

Current Status

Current release: v0.5.0

v0.5.0 includes repository onboarding analysis, workspace detection, Python and JavaScript/TypeScript import intelligence, package dependency analysis, circular package dependency detection, Docker Compose / Dockerfile application assembly, and change & impact analysis.

Roadmap

Next — Public API Surface

• Public exports and exported modules
• Package export surfaces and public interfaces

Future — Change & Impact Intelligence Expansion

• Richer package-level impact views
• Dependency path chains
• Machine-readable output formats (e.g., JSON)

The roadmap evolves based on real developer feedback.

Feedback and Contributing

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

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

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

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.