primer

# Primer The codebase brain that travels with you across every AI tool. **Real numbers on its own codebase:** 31 files → 190 symbols → 10 semantic clusters → architecture brief in 547 tokens. Full map in 17,095 tokens. Zero external calls. --- ## Getting Started ### Step 1 — Install and initialize ```bash npm install -g primer-ctx ``` Then run this in your project root: ```bash primer init ``` Primer scans your codebase and generates a `.primer/` folder with your symbol graph and context tiers. Takes a few seconds. --- ### Step 2 — Start watching *(optional but recommended)* ```bash primer watch ``` Run this in a terminal and leave it open while you code. It tracks your session automatically — which files you touch, which symbols you change — and refreshes your context tiers on every file save. No manual re-runs needed. --- ### Step 3 — Connect to your AI tool **For Claude Code, Cursor, or Windsurf** — run: ```bash primer serve ``` Then add this to your AI tool's MCP settings: ```json { "mcpServers": { "primer": { "command": "npx", "args": ["primer-ctx", "serve"], "cwd": "/path/to/your/repo" } } } ``` Restart the tool. Done — your AI now has full codebase context automatically on every conversation. **For ChatGPT, Claude.ai, Gemini, or any AI without MCP:** ```bash primer export > context.md ``` Paste `context.md` into your AI conversation before asking anything. Works with every AI. --- ### Step 4 — That's it Your AI now knows your architecture, remembers where you left off, and won't repeat suggestions you've already rejected. --- ## How it works end to end When you ask Claude Code *"fix the auth bug"* — before responding, Claude calls `get_context` which returns your architecture brief, your last session echo, and your veto constraints in one call. Claude answers like it's been on the project for weeks. When you switch from Cursor to Claude Code mid-session, the next AI automatically sees: *"last session you were working in the auth cluster, touched validateToken and handleRefresh"* — prepended to every response. --- ## Supported tools **Automatic (MCP):** Claude Code, Cursor, Windsurf, and any MCP-compatible host **Manual (export):** ChatGPT, Claude.ai, Gemini, and any other AI --- ## Commands | Command | What it does | |---------|-------------| | `primer init` | Scan repo, build symbol graph, generate context tiers | | `primer watch` | Track session + auto-refresh tiers on every file save | | `primer serve` | Start MCP server for AI tool connection | | `primer export` | Dump context to stdout — pipe to any file or paste anywhere | | `primer export --tier 2` | Export deeper tier (1, 2, or 3) | | `primer mcp-test` | Verify all 5 MCP tools return valid responses | | `primer diff` | Show symbol-level summary of uncommitted changes, by cluster | | `primer stats` | Print symbol count, cluster breakdown, token sizes | | `primer veto "message"` | Add a hard constraint to every future AI session | | `primer session end` | Manually end session and generate handoff echo | --- ## What the five features do **Layered context tiers** — Primer compresses your codebase into three sizes: - Tier 1 (~500 tokens): top symbols by importance, architecture brief - Tier 2 (~7k tokens): full module map grouped by semantic cluster - Tier 3 (~17k tokens): complete symbol index with every relationship **Session Echo** — tracks every file you save. When you switch AI tools, the next session starts with a brief: *where you were, what you touched, which cluster you were in*. Context carries over automatically. **Scar Tissue** — scans your git history for reverted commits. Every detected revert becomes a veto rule injected into every AI session: *do not suggest this again*. Your mistakes teach the AI, permanently. **`.primerignore`** — same syntax as `.gitignore`. Exclude files, directories, or patterns from the symbol graph. `dist/`, `build/`, `*.min.js`, and `*.generated.ts` are excluded by default. **`primer diff`** — before committing, see exactly which clusters and symbols you changed, and whether any veto rules apply to them. --- ## Verify your setup Before trusting your AI tool's responses, run: ```bash primer mcp-test ``` This simulates all 5 MCP tools and shows exactly what your AI will see. If all pass, you're ready. --- ## License MIT