{"id":47685220,"url":"https://github.com/git-pkgs/brief","last_synced_at":"2026-04-05T21:13:02.997Z","repository":{"id":344562260,"uuid":"1182218269","full_name":"git-pkgs/brief","owner":"git-pkgs","description":"A single-binary CLI tool that detects a software project's toolchain, configuration, and conventions, then outputs a structured report. ","archived":false,"fork":false,"pushed_at":"2026-03-15T20:45:58.000Z","size":264,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-15T21:30:49.817Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-pkgs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T07:50:13.000Z","updated_at":"2026-03-15T21:00:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/git-pkgs/brief","commit_stats":null,"previous_names":["git-pkgs/brief"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/git-pkgs/brief","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-pkgs%2Fbrief","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-pkgs%2Fbrief/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-pkgs%2Fbrief/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-pkgs%2Fbrief/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-pkgs","download_url":"https://codeload.github.com/git-pkgs/brief/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-pkgs%2Fbrief/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T14:46:54.385Z","updated_at":"2026-04-02T14:46:56.506Z","avatar_url":"https://github.com/git-pkgs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# brief\n\nA single-binary CLI tool that detects a software project's toolchain, configuration, and conventions, then outputs a structured report. Written in Go, 54 ecosystems, 355 tool definitions.\n\nbrief 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.\n\nIt does not score, grade, or judge. It reports facts.\n\n## Use with AI coding agents\n\nAdd this to your `CLAUDE.md`, `agents.md`, or equivalent agent instructions file:\n\n```\nBefore starting work on this project, run `brief .` to understand the toolchain,\ntest commands, linters, and project conventions. If on a branch, also run\n`brief diff` to see which parts of the toolchain are affected by your changes.\n```\n\nThe 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.\n\nTo let Claude Code run `brief` without prompting for approval each time, add this to `~/.claude/settings.json`:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"Bash(brief *)\"]\n  }\n}\n```\n\n## Install\n\n```\ngo install github.com/git-pkgs/brief/cmd/brief@latest\n```\n\nOr download a binary from [releases](https://github.com/git-pkgs/brief/releases).\n\n## Usage\n\n```\nbrief [flags] [path | url]        Detect project toolchain\nbrief diff [flags] [ref1] [ref2]  Detect only what changed between refs\nbrief missing [flags] [path]      Show recommended tooling gaps\nbrief enrich [flags] [path]       Detect and enrich with external data\nbrief list tools                  All tools in the knowledge base\nbrief list ecosystems             Supported ecosystems\nbrief schema                      JSON output schema\n```\n\nWorks on local paths, git URLs, and registry packages:\n\n```\nbrief .                                       Local directory\nbrief /path/to/project                        Any local path\nbrief https://github.com/expressjs/express    Git URL (cloned to temp dir)\nbrief npm:express                             Registry package (resolved to source repo)\nbrief gem:rails\nbrief crate:serde\nbrief pypi:requests\n```\n\nRemote 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.\n\nJSON when piped, human-readable on a TTY. Force either with `--json` or `--human`. Use `--category test` to filter to a single category.\n\n```\nbrief dev — /home/user/myproject\n\nLanguage:        Go\nPackage Manager: Go Modules (go mod download)\n                 Lockfile: go.sum\n                 9 runtime (223 total)\n\nTest:        go test (go test ./...)\nLint:        golangci-lint (golangci-lint run)  [.golangci.yml]\nFormat:      gofmt (gofmt -w .)\nDocs:        pkgsite (go run golang.org/x/pkgsite/cmd/pkgsite@latest)\nBuild:       GoReleaser (goreleaser release --clean)  [.goreleaser.yaml]\nSecurity:    govulncheck (govulncheck ./...)\nCI:          GitHub Actions  [.github/workflows/]\nCoverage:    go test -cover (go test -coverprofile=coverage.out ./...)\nDep Updates: Dependabot  [.github/dependabot.yml]\n\nStyle:       tabs (inferred)  LF\nLayout:      cmd/\n\n             OS: ubuntu-latest, macos-latest, windows-latest (CI matrix)\n\nResources:   README.md\nResources:   CONTRIBUTING.md\nResources:   LICENSE (MIT)\n\nGit:         branch main  71 commits\n             origin: git@github.com:user/myproject.git\n\nLines:       9295 code  397 files (scc)\n\n148.7ms  428 files checked  11/355 tools matched\n```\n\nUse `--verbose` to include homepage, docs, and repo links for each detected tool.\n\n## Diff\n\n`brief diff` runs the same detection but filters the report to only show tools, languages, and configuration relevant to files that changed. Useful for understanding what a branch or PR touches in terms of toolchain.\n\n```\nbrief diff                        Compare against default branch + uncommitted\nbrief diff main                   Compare main to HEAD + uncommitted\nbrief diff v1.0.0 v2.0.0         Compare between two refs\n```\n\nWith no arguments it auto-detects the default branch from `origin/HEAD`, falling back to `main` or `master`. The output lists changed files and only the toolchain entries those files relate to: if you changed a `.go` file, you'll see Go and its tools but not Python. If you changed `.golangci.yml`, you'll see golangci-lint. If you changed `go.mod`, you'll see dependency information.\n\nSame output format as `brief` -- JSON when piped, human-readable on a TTY.\n\n## Missing\n\n`brief missing` checks which recommended tool categories are absent for the project's detected ecosystems. It compares what's detected against five categories every project benefits from: test, lint, format, typecheck, and docs.\n\n```\nbrief missing .\nbrief missing --json .\n```\n\nFor each gap it suggests the canonical tool for that ecosystem, with the command to run and a link to docs.\n\n```\nDetected: python\n\nMissing recommended tooling:\n\n  Test         No test tool configured\n               Suggested: pytest (pytest)\n               https://docs.pytest.org\n\n  Lint         No lint tool configured\n               Suggested: Ruff (ruff check .)\n               https://docs.astral.sh/ruff/\n\n  Format       No format tool configured\n               Suggested: Black (black .)\n               https://black.readthedocs.io/en/stable/\n```\n\nTools built into the language runtime (go test, gofmt, cargo clippy, dart analyze, deno lint, etc.) are detected automatically when the language is present and won't show as missing.\n\n## Enrichment\n\n`brief enrich` runs the same scan, then fetches metadata from external APIs about the project itself: what packages it publishes, their download counts and dependents, runtime end-of-life status, and OpenSSF Scorecard.\n\n```\nbrief enrich .\nbrief enrich --json .\nbrief enrich --verbose .\n```\n\nData sources: [ecosyste.ms](https://ecosyste.ms) for published package metadata, [endoflife.date](https://endoflife.date) for runtime lifecycle, [OpenSSF Scorecard](https://securityscorecards.dev) for repo security.\n\n## What it detects\n\n54 language ecosystems with 355 tool definitions across 20 categories.\n\n**Languages (54):** Go, Ruby, Python, JavaScript, TypeScript, Rust, Java, Kotlin, Scala, Elixir, PHP, Swift, C#, Dart, Haskell, Clojure, Crystal, Julia, Nim, Zig, Lua, Perl, R, D, Elm, Gleam, Haxe, Nix, Deno, C, C++, Objective-C, Erlang, OCaml, F#, Groovy, Solidity, GDScript, Fortran, COBOL, Ada, VHDL, Verilog, Mojo, Roc, V, Odin, Scheme, Racket, Prolog, Tcl, Common Lisp, Emacs Lisp, plus CocoaPods and Conda ecosystems.\n\n**Test (46):** go test, Jest, Vitest, Mocha, AVA, RSpec, Minitest, pytest, JUnit, PHPUnit, ExUnit, EUnit, cargo test, Google Test, Catch2, Playwright, Cypress, MSW, Locust, Artillery, axe-core, Lighthouse CI, XCTest, dart test, deno test, kotlin.test, ScalaTest, crystal spec, Hspec, Alcotest, zig test, gleam test, and more.\n\n**Lint (31):** golangci-lint, ESLint, RuboCop, Ruff, Clippy, clang-tidy, Biome, Stylelint, commitlint, hadolint, ShellCheck, markdownlint, Semgrep, pre-commit, Lefthook, Husky, detekt, PHP_CodeSniffer, SwiftLint, Credo, HLint, elvis, clj-kondo, dart analyze, deno lint, WartRemover, Ameba, and more.\n\n**Format (25):** gofmt, Prettier, Black, rustfmt, isort, clang-format, ocamlformat, dprint, scalafmt, ktlint, SwiftFormat, StandardRB, PHP CS Fixer, mix format, erlfmt, Ormolu, dart format, deno fmt, dotnet format, zig fmt, crystal tool format, cljfmt, nimpretty, gleam format, google-java-format.\n\n**Build (48):** Webpack, Vite, esbuild, Rollup, Parcel, tsup, Rspack, GoReleaser, Mage, Rake, CMake, Make, Meson, Autotools, Hardhat, Foundry, Tailwind CSS, PostCSS, Sass, Less, UnoCSS, plus framework detection for Rails, Django, FastAPI, Express, Fastify, Koa, Hono, NestJS, AdonisJS, Gin, Phoenix, Spring Boot, Actix, Next.js, Nuxt, Remix, Angular, Ember.js, SolidJS, Qwik, Astro, Gatsby, SvelteKit, Eleventy.\n\n**Database (15):** ActiveRecord, Prisma, Alembic, Diesel, Ecto, Flyway, Liquibase, Goose, Dbmate, Drizzle, TypeORM, Sequelize, SQLAlchemy, GORM, SQLite.\n\n**Codegen (6):** Protobuf, Buf, OpenAPI, GraphQL Code Generator, ent, sqlc.\n\n**Infrastructure (7):** Terraform, Pulumi, Ansible, Kubernetes, Helm, AWS CDK, Serverless Framework.\n\n**CI/Deployment (7):** GitHub Actions, GitLab CI, Earthly, Dagger, Cloudflare Workers, Vercel, Netlify.\n\n**Container (3):** Docker, Docker Compose, Dev Container.\n\n**Monorepo (8):** Nx, Turborepo, Rush, Bazel, Pants, Lerna, pnpm workspaces, Go workspaces.\n\n**Release (6):** semantic-release, release-please, cargo-release, Changesets, git-cliff, conventional-changelog.\n\n**i18n (5):** i18next, gettext, Rails i18n, Crowdin, Transifex.\n\n**Docs (18):** pkgsite, Sphinx, MkDocs, Javadoc, Docusaurus, VitePress, Storybook, Jekyll, Doxygen, ExDoc, Dokka, phpDocumentor, cargo doc, dart doc, deno doc, Docsify, Starlight, and more.\n\n**Security (9):** govulncheck, npm audit, pip-audit, bundler-audit, cargo-audit, OWASP Dependency-Check, Snyk, Socket, and more.\n\n**Coverage (9):** go test -cover, coverage.py, SimpleCov, JaCoCo, c8, cargo-tarpaulin, Codecov, Coveralls, and more.\n\n**Also:** package managers (39), type checkers (6), dependency update bots (3), environment tools (9).\n\nRun `brief list tools` for the full list.\n\n## How it works\n\nDetection rules are data, not code. Each tool is defined in a TOML file under `knowledge/`, organized by ecosystem. Adding a new tool is a single TOML file with no Go code changes.\n\n```toml\n[tool]\nname = \"RSpec\"\ncategory = \"test\"\ndefault = true\nhomepage = \"https://rspec.info\"\ndescription = \"BDD testing framework for Ruby\"\n\n[detect]\nfiles = [\"spec/\", \".rspec\"]\ndependencies = [\"rspec\", \"rspec-core\"]\n\n[commands]\nrun = \"bundle exec rspec\"\nalternatives = [\"rake spec\", \"rspec\"]\n\n[config]\nfiles = [\".rspec\", \"spec/spec_helper.rb\"]\n```\n\nThe `default = true` flag marks a tool as the canonical choice for its category in that ecosystem. The `brief missing` command uses this to suggest the right tool when a category is absent.\n\nDetection uses five primitives: file/directory presence, dependency names from parsed manifests, file content matching, structured key existence (JSON/TOML), and ecosystem filtering to prevent cross-language false positives.\n\n## Library usage\n\nThe detection engine, knowledge base, and reporters are separate Go packages. Import them directly instead of shelling out to the binary:\n\n```go\nimport (\n    \"github.com/git-pkgs/brief\"\n    \"github.com/git-pkgs/brief/kb\"\n    \"github.com/git-pkgs/brief/detect\"\n    \"github.com/git-pkgs/brief/report\"\n)\n\nknowledgeBase, _ := kb.Load(brief.KnowledgeFS)\nengine := detect.New(knowledgeBase, \"/path/to/project\")\nr, _ := engine.Run()\nreport.JSON(os.Stdout, r)\n```\n\n## Contributing\n\nAdding a new tool: create a TOML file in the appropriate ecosystem directory under `knowledge/`, add test fixtures in `testdata/`, run `go test ./...`.\n\nAdding a new ecosystem: create a directory under `knowledge/`, add `language.toml` plus at least a package manager, test framework, and linter.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detection primitives and category definitions.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-pkgs%2Fbrief","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-pkgs%2Fbrief","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-pkgs%2Fbrief/lists"}