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 three 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.

3. brieflook api [path] — "What does this repository expose for other code to use, and where is that interface declared?" Reports statically discoverable public API surfaces, explicit exports, package re-exports, and manifest entry points.

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

3. Public API Surface Intelligence (brieflook api [path])

$ brieflook api .

    Public API Surface
+------------------------+
| Property   | Value     |
|------------+-----------|
| Repository | my-library|
+------------------------+

Python

Explicit Exports (__all__)
  src/my_package/__init__.py
    Client (line 8)
    create_client (line 9)

Package Re-exports (__init__.py imports)
  src/my_package/__init__.py
    models.User -> my_package.models.User (line 4)

JavaScript / TypeScript

Source Exports
  src/index.ts
    Client (class, line 12)
    createClient (function, line 25)
    default (default export, line 40)
    ClientConfig (interface, line 5)

Package Entry Points (package.json)
  package.json
    main: ./dist/index.js
    types: ./dist/index.d.ts
    . -> ./dist/index.js
    ./utils -> ./dist/utils.js

                 Summary
+---------------------------------------+
| Category                      | Count |
|-------------------------------+-------|
| Explicit exports (__all__)    |     2 |
| Package re-exports            |     1 |
| Inferred public definitions   |     0 |
| JavaScript/TypeScript exports |     4 |
| Declared package entry points |     4 |
+---------------------------------------+

What BriefLook Tells You

Capability	Onboarding / Change-management question it answers
Public API Surface Intelligence	What does this repository expose for other code to use, and where is that interface declared?
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

# Discover public API surface
brieflook api .
brieflook api src/brieflook

# 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

Public API Surface Intelligence

brieflook api [path] answers: "What does this repository expose for other code to use, and where is that interface declared?"

It inspects source files and package manifests to report statically discoverable public interfaces without executing repository code or calling external networks.

Supported Declarations

Python

• Explicit exports: Identifies __all__ lists and tuples of strings (including augmented assignments __all__ += [...]) in modules and __init__.py.
• Package re-exports: Discovers re-exports declared through package __init__.py files, such as from .sub import Item, from .sub import Internal as Public, and from . import module.
• Inferred public-looking definitions: For modules without an explicit __all__, identifies top-level non-private (non-_) functions, classes, and constants.

JavaScript & TypeScript

• Source exports: Named declarations (const, let, var, function, async function, class, interface, type, enum), default exports, explicit export clauses (export { ... }), and type exports (export type { ... }).
• Re-exports: Re-exports using export { ... } from, and wildcard re-exports (export * from, export * as ns from).
• Package entry points: Inspects package.json for entry points (main, module, types, typings) and conditional exports maps (including nested condition trees such as import, require, node, default).

Explicit Exports vs. Inferred Definitions

BriefLook strictly adheres to Evidence over Guessing:

• Explicit exports (__all__, export, manifest entry points) represent intentional public interface contracts committed by the author.
• Inferred definitions are non-private definitions identified by convention in modules that lack an explicit public contract. They are clearly labeled as inferred so developers know they are not guaranteed API contracts.

Static Analysis Limitations

BriefLook runs entirely offline and statically:

• Zero code execution: It never executes setup.py, imports Python modules, runs TypeScript compilers, or invokes Node.js.
• Dynamic exports disclosed: If __all__ is dynamically computed (e.g. [name for name in dir()] or function calls), or if syntax cannot be deterministically resolved, BriefLook reports an Analysis Limitation instead of guessing.

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.6.0 (Release Candidate) — Public API Surface Intelligence

v0.6.0 introduces Public API Surface Intelligence (brieflook api), identifying statically declared public exports, package re-exports, inferred definitions, and manifest entry points across Python and JavaScript/TypeScript codebases.

Roadmap

Current Milestone — Public API Surface Intelligence (v0.6.0)

• Statically discoverable public exports (__all__, ES module exports)
• Package re-exports and subpath exports maps
• Distinguishing declared contracts from inferred naming conventions
• Analysis limitation reporting for dynamic exports

Next — 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.