99 online 3 members  + Join RP Base  +
FreeTool

brief

by git-pkgs  ·  version 2026.11.10  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
600 KB
Code check
Clean
Licence
MIT
Released
Nov 2026

A single-binary CLI tool that detects a software project's toolchain, configuration, and conventions, then outputs a structured report.

brief
brief
A single-binary CLI tool that detects a software project's toolchain, configuration, and conventions, then outputs a structured report.

brief answers the bootstrap questions every AI coding agent, new contributor, and CI pipeline faces: what language is this, how do I install dependencies, how do I run the tests, what linter is configured.

It does not score, grade, or judge. It reports facts.
Use with AI coding agents
Add this to your CLAUDE.md, agents.md, or equivalent agent instructions file:

Before starting work on this project, run `brief .` to understand the toolchain,
test commands, linters, and project conventions. If on a branch, also run
`brief diff` to see which parts of the toolchain are affected by your changes.

The agent will get back structured information about the project's language, package manager, test runner, linter, formatter, build tools, and more, so it doesn't have to guess or ask you. On a feature branch, brief diff narrows that down to just the tools relevant to what's been changed, so the agent knows which linters to run, which test frameworks matter, and which config files are in play.

To let Claude Code run brief without prompting for approval each time, add this to ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(brief *)"]
  }
}

Install
brew install git-pkgs/git-pkgs/brief

Or with Go:

go install github.com/git-pkgs/brief/cmd/brief@latest

Or download a binary from releases.
Usage
brief [flags] [path | url]        Detect project toolchain
brief diff [flags] [ref1] [ref2]  Detect only what changed between refs
brief inspect [flags]   Inspect native objects in a binary or archive
brief missing [flags] [path]      Show recommended tooling gaps
brief threat-model [flags] [path] Threat categories implied by detected stack
brief sinks [flags] [path]        Dangerous functions in detected tools
brief enrich [flags] [path]       Detect and enrich with external data
brief outline [flags] [path|url]  Pack source tree into one document for an LLM
brief list tools                  All tools in the knowledge base
brief list ecosystems             Supported ecosystems
brief schema                      JSON output schema

Works on local paths, git URLs, and registry packages:

brief .                                       Local directory
brief /path/to/project                        Any local path
brief https://github.com/expressjs/express    Git URL (cloned to temp dir)
brief npm:express                             Registry package (resolved to source repo)
brief gem:rails
brief crate:serde
brief pypi:requests

Local scans inspect up to eight directory levels and 10,000 filesystem entries by default. Use --scan-depth N or --scan-limit N to change those bounds. External line counters have a two-second limit, configurable with --line-count-timeout D, and reports mark truncated scans. Set any of these three values to 0 to remove that bound. Use --skip dir1,dir2 to add directory exclusions, or --tracked to consider only files tracked by Git. --include-submodules scans initialized Git submodules recursively, including one below an otherwise skipped directory such as vendor/; neighboring vendored files and missing submodule worktrees stay excluded. When Rust source exists without a root Cargo.toml, brief uses the shallowest Cargo.toml within the scan depth as an additional manifest root. Cargo workspace member manifests are also checked for tool configuration.

Path roles filter the files used as detection evidence. Fixtures, vendored files, caches and build output do not contribute tools or dependencies. Language file matching also excludes generated files, tests, examples, benchmarks, fuzz targets, documentation and helper scripts. Ranking, inferred style and inferred source directories use the remaining source-role files and unclassified paths such as main.go. Project manifests can establish a language without counting as source files. Test files remain available for test-tool detection, and generated lockfiles remain dependency evidence. These filters do not change external line-count totals.

Remote sources are shallow-cloned by default. Use --depth 0 for a full clone, --keep to preserve the clone, or --dir ./somewhere to clone into a specific directory. Use --cache ./cache to keep one shallow checkout per HTTPS URL and reuse it across runs. Cache mode cannot be combined with --depth 0 or --dir.

Use brief --json --notebooks . to add Jupyter code-cell statistics. The notebooks field reports kernel language and its metadata source, code cells, physical source lines and bytes, with saved-output bytes kept separate. output_bytes counts the original serialized JSON for code-cell outputs fields, including JSON syntax and whitespace. It supports notebook formats 3 and 4, follows scan exclusions and reports malformed or oversized files. Parsing is limited to 32 files, 8.39 MB per file and 33.55 MB read in total. Opt-in scans can detect known kernel languages when code cells are present and the notebooks meet the existing language-evidence rules. Parsing remains opt-in and external line counts are retained; code and saved outputs are never returned.

Jupytext, nbstripout and Papermill are detected from dependencies or their project configuration. Notebook parsing is optional for these tool detections.

JSON when piped, human-readable on a TTY. Force either with --json or --human. Use --category test to filter to a single category.

JSON reports include a manifests array with the path, kind, and package ecosystem of every parsed manifest or lockfile. The dependencies array includes constraints from manifests and pinned packages from lockfiles, preserving directness and scope when the source records them. For Cargo, direct constraints come from Cargo.toml; pinned Cargo.lock e

…