Claude Bridge

A Claude Code skill that enables cross-project communication by spawning a second Claude CLI instance in another codebase. Ask questions, debug issues, and analyze code across projects — all from your current session.

The Problem

You're working in a frontend project and hit a 422 error from the backend. Normally you'd:

1. Switch to the backend repo
2. Open a new terminal / editor
3. Find the endpoint, read the code
4. Switch back to frontend
5. Try to remember what you found

With Claude Bridge, you just say:

ask backend about the GET /api/users/:id endpoint — I'm getting a 422

Claude spawns a second instance in the backend project, analyzes the code, and brings the answer back to your current session.

How It Works

┌─────────────────────┐         ┌─────────────────────┐
│   Your Session      │         │   Spawned Agent      │
│   (Agent A)         │         │   (Agent B)          │
│                     │         │                      │
│   Frontend project  │──echo──▶│   Backend project    │
│                     │  pipe   │                      │
│                     │◀──json──│   Reads code,        │
│   Gets the answer   │  stdout │   analyzes, responds │
│   and continues     │         │   and exits          │
└─────────────────────┘         └─────────────────────┘

Agent A sends a prompt via claude -p, Agent B analyzes the target project, returns structured JSON, and Agent A integrates the findings — all in one flow.

Installation

Quick Install

# Clone into your Claude Code skills directory
git clone https://github.com/enesgur/claude-bridge.git ~/.claude/skills/claude-bridge

# Create your project registry from the example
cp ~/.claude/skills/claude-bridge/projects.example.json ~/.claude/skills/claude-bridge/projects.json

Manual Install

1. Download SKILL.md and projects.example.json
2. Place them in ~/.claude/skills/claude-bridge/
3. Rename projects.example.json to projects.json
4. Edit projects.json with your project paths

Setup

Edit ~/.claude/skills/claude-bridge/projects.json to register your projects:

{
  "defaults": {
    "model": "sonnet",
    "mode": "read-only"
  },
  "projects": {
    "backend": {
      "path": "/Users/you/projects/backend-api",
      "description": "NestJS backend API",
      "model": "sonnet"
    },
    "frontend": {
      "path": "/Users/you/projects/frontend-app",
      "description": "Next.js frontend",
      "model": "haiku"
    },
    "shared": {
      "path": "/Users/you/projects/shared-libs",
      "description": "Shared type definitions and utils"
    }
  }
}

Field	Required	Description
path	Yes	Absolute path to the project root
description	Yes	Short description (helps Claude understand the project)
model	No	Override model for this project (defaults to defaults.model)

You can also manage projects via natural language:

• "bridge add project" — register a new project
• "bridge list" — show all registered projects
• "bridge remove backend" — unregister a project

Usage

By Alias

ask backend about the users endpoint
bridge to frontend — what component renders the dashboard?
check backend for breaking changes

By Explicit Path

ask the project at /path/to/repo about the auth flow
bridge to /tmp/some-repo — what framework is this using?

With Model Override

ask backend with opus about the architecture
ask backend with haiku — quick question, what port does it run on?

Follow-up Questions

After a bridge query, you can continue the conversation:

bridge resume — also check the middleware
follow up with backend — what about pagination?
ask backend again — show me the error handler too

Use Cases

Ask About an API Endpoint

ask backend about the GET /api/users/:id endpoint — I'm getting a 422

Agent B finds the route handler, checks validation rules, and returns the expected request/response format.

Debug a Contract Mismatch

bridge to backend — the frontend expects { user: { id, name, email } }
but we're getting { data: { userId, fullName, emailAddress } }

Agent B locates the serializer and shows the actual response structure.

Check for Breaking Changes

ask backend with opus — did recent commits break any of our user endpoints?

Agent B checks git history and diffs for changes to the specified endpoints.

Get TypeScript Types from Backend

ask backend — give me TypeScript interfaces for /api/auth/* endpoints

Agent B extracts schemas and returns them as TypeScript interfaces.

Understand a Sibling Service

bridge to payment-service — how does the webhook verification work?

Agent B analyzes the codebase and explains the webhook flow.

Model Selection

Models are resolved in priority order:

Priority	Source	Example
1	Explicit in message	"ask backend **with opus** about..."
2	Project config	projects.backend.model
3	Global default	defaults.model
4	Fallback	sonnet

When to Use Each Model

Model	Best For
haiku	Quick lookups, simple questions, listing endpoints
sonnet	Code analysis, debugging, understanding flows
opus	Deep architectural analysis, complex reasoning

How It Works (Technical)

The skill uses Claude CLI's -p (print) mode to spawn a non-interactive agent:

# Read-only query
echo "<prompt>" | claude -p \
  --model <MODEL> \
  --output-format json \
  --permission-mode plan \
  --add-dir <TARGET_PROJECT_PATH> \
  2>/dev/null

The JSON response contains:

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Agent B's analysis...",
  "session_id": "uuid-for-resumption",
  "total_cost_usd": 0.05,
  "duration_ms": 3000
}

• result — the actual answer
• session_id — used for --resume in follow-up queries
• is_error — error detection

Session Resumption

Follow-up queries reuse the previous session context:

echo "<follow-up>" | claude -p \
  --resume <SESSION_ID> \
  --output-format json \
  2>/dev/null

Requirements

• Claude Code CLI v2.0+
• Active Claude subscription (Pro, Team, or Enterprise)

Safety

• Default mode is read-only (--permission-mode plan) — Agent B cannot modify files
• Edit mode requires explicit user confirmation
• --dangerously-skip-permissions is never used
• projects.json is gitignored (contains local paths)

File Structure

~/.claude/skills/claude-bridge/
├── SKILL.md                 # Skill definition (how Claude uses this)
├── projects.json            # Your project registry (gitignored)
├── projects.example.json    # Template for new users
├── README.md
├── LICENSE
└── .gitignore

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/multi-project-query)
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

Ideas for contribution:

• Parallel multi-project queries (ask backend AND frontend simultaneously)
• Project auto-discovery (scan workspace for projects)
• Response caching for repeated queries
• Custom prompt templates per project

License

MIT License — see LICENSE for details.