Some coding chats can connect to a local folder or GitHub repo. Others cannot, and sometimes I want to hand over only a small, reviewable slice of a project for one task. Collecting those files by hand gets tedious. That is why I built Codebase Brief.
Codebase Brief is a local Python CLI. Give it a repository and a task; it suggests files and explains why, then builds a compact Markdown handoff with excerpts and paths. You can keep, remove, or add suggestions. An optional Git base ref prioritizes changed files and supported direct importers.
It makes no AI calls and does not upload repository contents. File selection is heuristic: it can miss useful files or include irrelevant ones. Review the suggestions and the brief before sharing. If your assistant already reads your current working tree and that access suits you, its built-in tools may be simpler. Codebase Brief is for chats without that access, or when you want a smaller, explicit handoff. The README explains when it fits.
To preview it with a temporary sample project:
pipx install codebase-brief
brief --demo
To make a brief for your own task:
brief "/path/to/your/repo" --task "Trace the login flow" --copy
Replace the example path and task with yours. If you want Git changes prioritized, add --base main only when main is the right base ref for your repo. The brief is copied to your clipboard; paste it into your chat and check it before sharing. If you already installed it, use pipx upgrade codebase-brief.
I would like feedback from developers who try it on a repository they know: Which suggested files did you remove? Which useful ones did you add? Did the brief give your assistant enough to get started? The CLI prints a summary of those changes. You can share it through the tester feedback form—please remove private paths or details first.
I made Codebase Brief. The source, screenshots, and full instructions are on GitHub.
Top comments (0)