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