Primer

AI agents are powerful. They're also forgetful, risky, and unaccountable. Primer fixes all three.

Primer is a VS Code extension that gives every AI coding agent persistent memory, enforced guardrails, and a live audit trail — so you can finally step away and trust the work gets done right.

Works with Claude, Cursor, Windsurf, Zed, and any MCP-compatible agent.

The problem

Every developer using AI agents has been burned.

The agent forgot what it was doing yesterday. It overwrote the wrong file. You told it "don't touch .env" and it did anyway. You came back to a broken build and no idea what changed.

AI agents are remarkably capable — but they have no memory, no rules, and no accountability. You end up babysitting them instead of shipping.

Primer adds all three.

What your agents get

🧠 Memory that persists

Facts, decisions, file history, and handoff notes survive across sessions, machines, and even different AI agents. Start a session in Claude on your phone; continue in Cursor on your laptop. Everything is there.

🛡️ Guardrails that actually work

Define which files are off-limits. Primer intercepts every write attempt and returns allow, warn, or block — before anything happens. .env, *.pem, migrations — never touched without explicit approval.

📋 An audit trail you can trust

Every file change is captured in real-time by the file watcher. See exactly what your agent did, when, and why — directly in the VS Code sidebar.

How it works

  Claude.ai  ·  Cursor  ·  Windsurf  ·  Any MCP agent
        │
        │  MCP over HTTP/SSE
        ▼
  ┌─────────────────────────────────────────┐
  │      Cloudflare Relay (primer-relay)    │  ← No ports exposed. No server to run.
  │      primerctx.workers.dev             │
  └──────────────┬──────────────────────────┘
                 │  WebSocket
                 ▼
  ┌─────────────────────────────────────────┐
  │   Primer VS Code Extension              │
  │   · MCP daemon (12 tools)               │
  │   · Memory & guardrails engine          │
  │   · Real-time sidebar                   │
  └──────────────┬──────────────────────────┘
                 │
        ┌────────┴────────┐
        ▼                 ▼
  Local filesystem    Supabase
                      (events, sessions,
                       live dashboard)

Quick start

1. Install the extension

Search joshuathinks.primer-agent in VS Code, or install from the Marketplace.

2. Sign in and generate a relay URL

Click Sign in with Google in the Primer sidebar, then click + New URL to get your agent relay URL.

3. Connect your agent

Claude.ai: Settings → Integrations → Add integration → paste the relay URL.

Cursor / Claude Desktop / Windsurf:

{
  "mcpServers": {
    "primer": {
      "url": "https://primer-relay.primerctx.workers.dev/mcp/YOUR_UUID?token=YOUR_TOKEN"
    }
  }
}

4. Add the system prompt

Paste this into your agent's custom instructions once — it works forever:

You have Primer MCP connected. ALWAYS start each session:
  primer_agent_brief({ session_id: "unique-uuid", agent: "your-name" })

Rules:
• primer_list_dir before navigating any files
• primer_str_replace for ALL edits — never overwrite whole files
• primer_agent_learn to save facts for future sessions
• primer_agent_handoff at end of every session

MCP Tools (12)

| Tool | Description | |---|---| | primer_agent_brief | Full project briefing — memory, pending plans, recent activity, guardrails | | primer_agent_check | Gate before any write/delete — returns allow / warn / block | | primer_agent_learn | Persist a fact, decision, or observation to project memory | | primer_agent_handoff | End session — writes summary + next steps for the next agent | | primer_read_file | Read a file through guardrails (.env, *.pem blocked) | | primer_write_file | Write a file — guardrails enforced, logged immediately | | primer_str_replace | Surgical code edit — replaces exactly one string, safe for any file size | | primer_list_dir | File tree of the project — use before any file operation | | primer_file_history | What agents did to a specific file — reads, writes, patches | | primer_add_plan | Save a task visible in every future brief until marked done | | primer_list_plans | List all pending plans | | primer_done_plan | Mark a plan complete |

Guardrails

Rules are defined in .primer/agent/rules/ (auto-generated on first use).

| Level | Behavior | |---|---| | block | Agent cannot proceed. Action denied and logged. | | warn | Agent is warned. Can proceed with caution. | | allow | Unrestricted. |

Defaults: .env and **/.env* are blocked. **/*.pem is blocked. **/migrations/** warns.

Session resumption

When an agent disconnects and reconnects (e.g. Claude.ai tab refresh), the relay automatically injects the last 5 actions into the next primer_agent_brief call — so the agent continues exactly where it left off, no re-explanation needed.

Project structure

primer-agent/        VS Code extension + MCP daemon
├── src/
│   ├── daemon/      MCP server, tools, HTTP/SSE, workspace sync
│   ├── ui/          Sidebar webview
│   ├── agent/       Memory, sessions, conflict detection
│   └── extension.ts Entry point, command registration
└── out/             Compiled (daemon.js, sidebar-webview.js)

primer-relay/        Cloudflare Worker
└── src/index.ts     Durable Object relay + OAuth + token management

primer-web/          Next.js dashboard — getprimer.dev
└── src/app/
    ├── dashboard/   Overview, live feed, sessions, audit, memory, rules
    └── auth/        Google OAuth

Development

# Extension
cd primer-agent && npm install
npm run build:all     # compile daemon + webview
npx vsce package      # build .vsix

# Relay
cd primer-relay
npx wrangler dev      # local
npx wrangler deploy   # production

# Dashboard
cd primer-web && npm install
npm run dev           # localhost:3000

License

MIT — built by Joshua