Metadata-Version: 2.4
Name: codebase-brief
Version: 0.1.0
Summary: Local-first CLI that builds task-focused context briefs from code repositories
Author: Mohamed Maggy
License-Expression: MIT
Project-URL: Homepage, https://github.com/mohamed1111111m/codebase-brief
Project-URL: Repository, https://github.com/mohamed1111111m/codebase-brief
Project-URL: Issues, https://github.com/mohamed1111111m/codebase-brief/issues
Keywords: developer-tools,codebase,context,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Codebase Brief

[![Tests](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)

**Give a coding assistant a clear map of a repository before it starts a task.** Codebase Brief reads a local project and creates a compact Markdown brief with relevant files, recent Git changes, and source paths you can check.

It works locally, without an AI service or account. You choose what to do with the brief: review it, save it, or paste it into Claude Code, Cursor, OpenCode, Codex, or another coding assistant.

## See it in action

The first image is a terminal-style rendering of the app's actual numbered menu. The sample brief was generated by running Codebase Brief on a small example repository with a Git base ref.

![Codebase Brief's colorful guided menu](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/guided-menu.png)

![Example context brief showing task, repository details, recent changes, and cited files](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/sample-context-brief.png)

[Watch the 12-second product walkthrough](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/product-hunt-demo.mp4).

## Get started

You need Python 3.10 or newer. Git is optional, but it enables recent-history and base-diff details.

Once the first PyPI release is available, install it in a virtual environment and launch the menu:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade codebase-brief
codebase-brief
```

Until then, install the current version directly from GitHub:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install git+https://github.com/mohamed1111111m/codebase-brief.git
codebase-brief
```

On macOS or Linux, activate the environment with `source .venv/bin/activate` after creating it with `python3 -m venv .venv`.

If the `brief` command is not available, use `python -m context_inject` while that same virtual environment is active.

## Use the menu

When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:

1. **Build a context brief** — describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
2. **Choose a different project** — point the tool at another local repository or source folder.
3. **Help and examples** — see the workflow and an example command.
0. **Exit** — close the menu.

Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or type `none` for an overview without source excerpts. Then choose whether to show the result, save it, choose another output path, or copy it to your clipboard. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.

For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.

## Run it with a command

You can skip the menu and generate a brief directly:

```powershell
codebase-brief "C:\work\my-app" --task "Add authentication middleware" --base main --budget 2400 --output context.md
```

Replace the example folder and task with your own. `--base main` prioritizes files changed between `main` and the current `HEAD`; omit it if you do not want a Git diff. `--output context.md` saves the result to that path. Without `--output`, the brief is printed in the terminal.

To copy the result directly to your clipboard, use `--copy` instead of `--output`:

```powershell
codebase-brief "C:\work\my-app" --task "Find the login flow" --copy
```

The generated Markdown is a starting map for your assistant, not a complete copy or analysis of the repository. Review it, then paste it into the coding assistant where you want to work.

## What it includes

- Project documentation and common stack manifests, such as `package.json` and `pyproject.toml`.
- Recent Git commit subjects and changed paths when Git is available.
- A short list of task-related files with a note explaining each suggestion.
- Small excerpts from selected files, within the requested size budget.
- Source paths throughout the brief so you can open and verify the material.

The file picker uses task words, recent changes, selected Git diffs, common entry points, and direct local Python or JavaScript/TypeScript imports. These are simple heuristics, not semantic code analysis. It traces at most one direct import hop for supported languages, so it can miss relevant files.

## Privacy and limitations

- Repository reading and brief generation happen on your computer. The application has no AI calls, telemetry, or hosted service.
- The tool does not write to the target repository just to read it or generate a brief. It writes a file only when you choose a save option; menu option 2 saves `context.md` in the current working folder, which may be the target repository.
- Common credential files, ignored files, generated files, and private-key files are excluded. Some recognizable secret formats and assignments are redacted.
- Filtering is best-effort, not a security guarantee or full secret scan. Review the brief before sharing it, especially when working with private code.
- The size budget is approximate: it estimates tokens from character count and is not tied to a particular model tokenizer.
- Without Git, the tool still reads supported documentation and manifests, but cannot include Git history or diff details.

## Development

Clone the repository, create a virtual environment, and install the project in editable mode:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --editable .
python -m unittest discover -s tests -v
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution notes, [CHANGELOG.md](CHANGELOG.md) for project changes, and [LICENSE](LICENSE) for the MIT terms.

## Help shape Codebase Brief

This is an early open-source project. If you try it, feedback about which suggested files were useful or missing is especially helpful. Use [GitHub Issues](https://github.com/mohamed1111111m/codebase-brief/issues) for reproducible bugs and concrete feature requests. The [launch kit](docs/launch-kit.md) has a short demo plan, the [Product Hunt draft](docs/product-hunt-launch.md) contains prepared listing copy, and PyPI setup is in [PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).

