Case Study

claude-code-bridge

Context compounds. It never resets.

A local MCP server that bridges Claude Mac app and Cursor. Strategy decisions from Claude auto-sync to your project files. When you open Cursor, Claude Code already knows where things stand. No copy-paste, no re-explaining.

GitHub Back to Portfolio

Shipped in 2 Hours

Built and working

Context Engineering

Strategy to code

Used Daily

6 projects

MCP Native

Anthropic SDK

At a Glance

Developer Tool

Type

Context Engineering

Domain

Shipped

Status

TypeScript + MCP

Stack

Sections

The Problem

You Strategize in One Place, You Build in Another

You use Claude to think through architecture, weigh tradeoffs, and make product decisions. Then you switch to Cursor to build. The moment you switch, the context is gone. You re-explain what was decided, repeat the constraints, and hope you remember what you agreed on ten minutes ago.

This is not a tooling problem. It is a context engineering problem. The decisions exist, they were made in a real conversation, but they are trapped in a chat window that your code editor cannot read.

I built claude-code-bridge in two hours to fix this for myself. It saves hours of manual copy-paste every week, reduces the errors that come from re-explaining context from memory, and keeps a clean CLAUDE.md that any AI coding agent can read automatically. The bridge runs across six active projects today.

Workflow

How It Works

Step 1

Strategize in Claude Mac app

Think through architecture, product decisions, and tradeoffs in a normal Claude conversation. No special syntax, no commands.

Step 2

claude-code-bridge writes decisions

At the end of every strategy session, Claude automatically writes technical decisions to CLAUDE.md and product decisions to docs/decisions.md in your project.

Step 3

Open Cursor

Cursor reads CLAUDE.md at session start via .cursorrules. Claude Code has full context before you type a single command.

Step 4

Build with context

Claude Code knows the stack, the constraints, the decisions, and the history. No re-explaining. No copy-paste.

Step 5

Next session compounds

The next strategy session reads the existing log and builds on top of it. Every session adds to the context. It never resets.

Stack

TypeScriptNode.jsMCP SDKAnthropic

Architecture

Two Files, Two Purposes

CLAUDE.md

Technical context for Claude Code. Stack, architecture, code rules, and a running log of technical decisions. Claude Code reads this at the start of every Cursor session. Think of it as the project's working memory.

docs/decisions.md

Product decision log for humans. Why certain decisions were made, what tradeoffs were accepted, what alternatives were rejected. Append-only, never edited. Useful for PMs and engineers reviewing your work.

Design Decisions

Why It Works This Way

Two files, not one

Technical context (CLAUDE.md) and product reasoning (decisions.md) serve different readers. Claude Code needs stack and constraints. Humans need the why behind decisions. Mixing them makes both worse.

Append-only decision log

Product decisions are never edited. If a decision changes, a new entry explains why. This creates an auditable trail of product thinking that compounds over time.

Local MCP server, not a cloud service

Runs on your machine, reads and writes to your local filesystem. No API keys, no cloud dependency, no data leaving your laptop. Setup once, works forever.

Three tools, not ten

read_file, write_decisions, create_file. That is the entire surface area. Deliberate minimalism. Every tool added is a tool that can break or confuse the model.

stdio transport, not HTTP

Claude Mac app communicates with MCP servers via stdio (standard input/output). No ports, no networking, no firewall issues. The simplest possible transport for a local tool.

.cursorrules as the trigger

A one-line .cursorrules file tells Cursor to read CLAUDE.md at the start of every session. No plugin, no extension, no configuration UI. One file, automatic context loading.

Limitations

Honest Limitations

Mac only
Claude Mac app is required. Windows and Linux users cannot use this today.
No conflict resolution
If two sessions write to CLAUDE.md simultaneously, last-write-wins. Not a problem for solo builders, but would need locking for teams.
Manual setup per project
Each project needs a CLAUDE.md, a docs/decisions.md, and a .cursorrules file created manually. A CLI scaffolding tool would reduce this friction.
Context window limits apply
CLAUDE.md is read into the context window. Very large project logs could eventually exceed limits. Periodic cleanup keeps it manageable.

Architecture and Tools

How It Looks

Roadmap

What's Next

CLI scaffolding tool: `npx claude-code-bridge init` to create CLAUDE.md, decisions.md, and .cursorrules in any project
Multi-agent support: bridge context across Claude, GPT, and Gemini sessions
Team mode: shared decision log with conflict resolution for multi-contributor projects
VS Code extension: bring the bridge to non-Cursor editors