# 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

```bash
cd briefcase
pip install -e .
```

Set your Anthropic API key for AI powered summaries (optional  heuristic fallback works without it):

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

## Quick Start

Inside any project folder:

```bash
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:

```bash
briefcase serve
```

Add to your Cursor MCP config:

```json
{
  "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

```bash
# 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

```bash
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