agentbrief
ShawWang1996/agentbrief
Generate repo-grounded task briefs for AI coding agents like Codex, Claude Code, and Cursor.
Instalação
npx convez-ai ShawWang1996/agentbrief1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
AgentBrief
Repo-grounded task briefs for AI coding agents.
AgentBrief turns a repository and an engineering task into a portable brief that can be handed to Codex, Claude Code, Cursor, Copilot, or a generic LLM chat. It collects the files that matter, detects validation commands, redacts likely secrets, and renders a task contract with acceptance checks.
The goal is simple: make coding agents start from repo evidence instead of a vague prompt.
Why This Exists
AI coding agents are useful, but they still fail on ordinary engineering details: missing setup commands, stale assumptions about project structure, oversized context, and accidental secret exposure. Existing repo packers are good at bundling files. AgentBrief focuses on the task handoff layer around those files:
- What is the objective?
- What files are relevant?
- What commands prove the work is done?
- What sensitive values must not be copied into prompts?
- What prompt shape works across different agents?
Features
agentbrief init: create a smallagentbrief.tomltask contract.agentbrief doctor: inspect included files and likely sensitive data before sharing.agentbrief pack: generate a Markdown or JSON context package.agentbrief render: generate Codex, Claude, Cursor, or generic agent prompts.- Local-first by default: no network calls, no model calls, no telemetry.
- Zero runtime dependencies beyond Python 3.9+.
Quick Start
python -m pip install -e .
agentbrief init
agentbrief pack
agentbrief render --target codex
This creates:
agentbrief.toml: task, acceptance checks, include/exclude rules.agentbrief.md: repo-grounded context package.agentbrief-prompt.md: agent-specific prompt wrapper.
Example Config
[task]
title = "Fix the failing checkout flow"
objective = "Find the root cause, implement the smallest safe fix, and verify the checkout tests pass."
acceptance = [
"The failing checkout test passes",
"Existing payment behavior is preserved",
"No credentials or generated artifacts are included",
]
[context]
include = ["src/**", "tests/**", "pyproject.toml", "package.json", "README.md"]
exclude = ["dist/**", "build/**", "*.lock"]
max_file_bytes = 64000
max_total_bytes = 750000
[commands]
test = "python -m unittest discover"
lint = "python -m compileall agentbrief"
CLI
agentbrief init --root /path/to/repo
agentbrief doctor --root /path/to/repo --strict
agentbrief pack --root /path/to/repo --format markdown --output agentbrief.md
agentbrief pack --root /path/to/repo --format json --output agentbrief.json
agentbrief render --root /path/to/repo --target claude --output claude-brief.md
What The Brief Contains
- Task title, objective, and acceptance checks.
- Detected and configured validation commands.
- Existing agent instruction files such as
AGENTS.md,CLAUDE.md, and Cursor rules. - Language/file manifest with SHA-256 prefixes.
- Sensitive-data findings with matched values redacted.
- Included file contents in path-labeled code fences.
- Agent instructions for scoped edits and validation.
Design Principles
- Evidence first: every agent handoff should include actual repository files, not only prose.
- Verification first-class: acceptance checks and commands belong in the brief.
- Private by default: local execution and redaction are core behavior, not add-ons.
- Agent portable: the same brief should work across competing agent tools.
- Small core: no framework lock-in, no hosted dependency, no mandatory LLM key.
Development
python -m unittest discover
python -m compileall agentbrief
Roadmap
- Smarter git-diff and issue-based context selection.
- Token budget estimation and context ranking.
- Native
AGENTS.md, Claude skill, Cursor rule, and Copilot instruction generation. - MCP server mode for live agent consumption.
- GitHub Action that attaches an AgentBrief to issues or pull requests.
- Plugin API for project-specific scanners and command detectors.
See docs/ROADMAP.md and docs/PRODUCT_SPEC.zh-CN.md.
For release operations and launch copy, see docs/LAUNCH.md.
Security
AgentBrief includes heuristic secret detection and redaction, but no scanner is perfect. Run agentbrief doctor --strict before sharing a brief outside your local machine.
See SECURITY.md.
License
MIT