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
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
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,
To let Claude Code run
Install
Or with Go:
Or download a binary from releases.
Usage
Works on local paths, git URLs, and registry packages:
Local scans inspect up to eight directory levels and 10,000 filesystem entries by default. Use
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
Remote sources are shallow-cloned by default. Use
Use
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 reports include a
…
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/briefOr with Go:
go install github.com/git-pkgs/brief/cmd/brief@latestOr 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 schemaWorks 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:requestsLocal 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…