Briefcase
Carry your codebase's context wherever you code.
Never re explain your project to an AI again. Briefcase scans your codebase, generates compact AI summaries, tracks changes via git, stores your "why" decisions, and exports a paste ready briefing for Claude, Cursor, Codex, or any AI tool.
Why Briefcase?
Every time you switch AI tools or accounts, you lose context. Briefcase maintains a living briefing document about your project tech stack, file summaries, architecture decisions so the next AI understands your codebase in seconds.
Install
cd briefcase
pip install -e .
Set your Anthropic API key for AI powered summaries (optional heuristic fallback works without it):
export ANTHROPIC_API_KEY=sk-ant-...
Quick Start
Inside any project folder:
briefcase init # Set up .briefcase/ in this project
briefcase scan # Scan and summarize all significant files
briefcase export # Copy-paste context into your AI chat
Commands
| Command | Description |
|---|---|
briefcase init |
Initialize Briefcase in the current project |
briefcase scan |
Full scan summarize all significant files |
briefcase update |
Incremental update only changed files (via git) |
briefcase export |
Output paste-ready briefing markdown |
briefcase note "..." |
Save a decision note (use -f path to attach to a file) |
briefcase notes |
List all decision notes |
briefcase log |
Show scan history timeline |
briefcase diff |
Show briefing changes since last export |
briefcase status |
Health check — how fresh is your briefing? |
briefcase focus <path> |
Deep-dive export for one file/folder |
briefcase serve |
Run as MCP server for direct AI tool integration |
How It Works
briefcase scan / update
│
▼
scanner.py ──► walks project, detects tech stack, skips junk
│
▼
git_tracker.py ──► finds changed files since last scan
│
▼
summarizer.py ──► Claude API (or heuristics) per file
│
▼
storage.py ──► SQLite in .briefcase/briefing.db
│
▼
exporter.py ──► paste-ready markdown context block
What gets stored
your-project/
└── .briefcase/
├── briefing.db # SQLite — summaries, notes, history
└── config.json # Tech stack, settings
MCP Server (Stretch)
Run Briefcase as an MCP server so Cursor or Claude can pull context directly:
briefcase serve
Add to your Cursor MCP config:
{
"mcpServers": {
"briefcase": {
"command": "briefcase",
"args": ["serve"],
"cwd": "/path/to/your/project"
}
}
}
Available MCP tools: get_briefing, get_briefing_diff, get_project_overview, get_notes, get_file_summary.
Examples
# First time in a project
briefcase init
briefcase scan
# After coding for a while
briefcase update
briefcase export -o CONTEXT.md
# Remember why you made a choice
briefcase note "Chose SQLite over Postgres — single-user, no server needed" -f briefcase/storage.py
briefcase notes
# Before switching AI tools
briefcase diff
briefcase status
Development
pip install -e ".[dev]"
pytest
Project Structure
briefcase/
├── briefcase/
│ ├── cli.py # CLI commands
│ ├── scanner.py # Project walker + tech stack detection
│ ├── summarizer.py # Claude API / heuristic summaries
│ ├── git_tracker.py # Git diff integration
│ ├── storage.py # SQLite persistence
│ ├── notes.py # Decision notes
│ ├── exporter.py # Paste-ready export
│ └── mcp_server.py # MCP server mode
├── tests/
├── pyproject.toml
└── README.md
License
MIT
