Generate a compact repository brief so coding agents and maintainers know what matters before they edit code.
repo-brief scans a local repo and summarizes stack, test commands, CI, docs, agent instructions, env-file risks, and launch gaps in Markdown or JSON. No network calls. No API keys. No .env contents read.
Coding agents often waste the first turn rediscovering the same repo facts: package manager, test command, CI files, docs, hidden env assumptions, and missing contributor basics.
Most repo summaries are either too broad or too manual. repo-brief gives a fast, deterministic first-pass context file that humans can inspect and agents can consume.
python -m pip install .
repo-brief examples/sample-repoWrite a brief for the current repo:
repo-brief . --output AGENT_BRIEF.mdGet structured output for tooling:
repo-brief . --format json --output repo-brief.json# Repo Brief: sample-agent-app
Compact repository context for coding agents and maintainers.
## Snapshot
- Files scanned: 7 / max 5000
- Truncated: no
## Detected Commands
| Task | Command | Source |
| --- | --- | --- |
| install | `npm install` | package.json |
| test | `npm test` | package.json scripts |
| lint | `npm run lint` | package.json scripts |
## Risks And Gaps
- No obvious gaps detected
From this repository:
python -m pip install .After publishing, install with pipx or pip:
pipx install repo-briefScan a repo and print Markdown:
repo-brief /path/to/repoCreate a context file for a coding-agent session:
repo-brief . --output AGENT_BRIEF.mdUse JSON in another tool:
repo-brief . --format json | jq '.commands'Limit scan size for large monorepos:
repo-brief . --max-files 1000Include hidden files except known secret files and heavy ignored directories:
repo-brief . --include-hidden- Package metadata:
package.json,pyproject.toml,Cargo.toml,go.mod, and common lockfiles. - Commands: package scripts, Python install, unittest, compile checks, and Makefile targets.
- CI: GitHub Actions, GitLab CI, and CircleCI config files.
- Tests: common test directories and file naming patterns.
- Docs: README, contributing guide, changelog, security policy, license, and
docs/. - Agent instructions:
AGENTS.md,CLAUDE.md,GEMINI.md, Cursor rules, and Copilot instructions. - Environment files: templates are listed; sensitive
.env*files are skipped.
- Create a repo handoff brief before starting a coding-agent run.
- Add
AGENT_BRIEF.mdto onboarding docs for maintainers. - Check whether a small open-source repo has basic launch readiness.
- Generate JSON for internal developer-experience tooling.
- Spot missing README, CI, tests, or agent instructions before opening a PR.
treeshows structure, but not commands, risks, or repo conventions.- README files explain intent, but often omit exact verification commands.
- Agent-specific memory files help one tool, while
repo-briefemits portable Markdown and JSON. - Full static-analysis tools go deeper, but need more setup and maintenance.
- Command detection is heuristic. Always verify commands before destructive or production work.
- YAML files are listed, not parsed.
- Monorepo package discovery is intentionally shallow in v0.1.
- Secret scanning is not the goal; sensitive env filenames are only detected and skipped.
- Python 3.9+ is required.
- Better monorepo workspace summaries.
- Optional GitHub Actions job-name extraction without third-party dependencies.
- Config file for custom command hints and ignored paths.
--fail-on-riskmode for CI checks.
See CONTRIBUTING.md. Small, well-tested improvements are preferred.
MIT. See LICENSE.