claude-bridge

Use when the user needs to query, analyze, or collaborate with another project's codebase by spawning a second Claude CLI instance. Enables cross-project communication between a frontend and backend, microservices, or any two codebases. Triggers on phrases like "ask backend", "bridge to", "check the other project", "query project X".

SKILL.md

---
name: claude-bridge
description: Use when the user needs to query, analyze, or collaborate with another project's codebase by spawning a second Claude CLI instance. Enables cross-project communication between a frontend and backend, microservices, or any two codebases. Triggers on phrases like "ask backend", "bridge to", "check the other project", "query project X".
---

# Claude Bridge Skill Guide

## Overview

Spawns a second Claude CLI instance (`claude -p`) targeting a different project directory. The current session (Agent A) sends a prompt, receives structured JSON output from Agent B, and integrates the findings. Supports multi-turn cross-project conversations via session resumption.

## Project Registry

**Config file:** `~/.claude/skills/claude-bridge/projects.json`

Read this file at the start of every bridge invocation. It contains:
- `defaults` — fallback model and mode
- `projects` — alias-to-path mapping with optional per-project overrides

```json
{
  "defaults": {
    "model": "sonnet",
    "mode": "read-only"
  },
  "projects": {
    "backend": {
      "path": "/absolute/path/to/backend",
      "description": "NestJS backend API",
      "model": "sonnet"
    }
  }
}
```

**To add a new project**, edit this JSON file. Each key is an alias usable in natural language.

## How to Invoke

The skill supports **3 ways** to specify the target project, from most convenient to most explicit:

### 1. By Alias (recommended for repeated use)

User says something like:
- "ask **backend** about the users endpoint"
- "bridge to **frontend** — what component renders the dashboard?"
- "check **backend** for breaking changes"

**Flow:**
1. Read `projects.json`
2. Match the alias (e.g., "backend") to its registered path
3. Use the project's configured model (or `defaults.model`)
4. Execute immediately — no questions needed

### 2. By Explicit Path

User says something like:
- "ask the project at **/Users/enesgur/work/payment-service** about..."
- "bridge to **/tmp/some-repo** — analyze the auth flow"

**Flow:**
1. Extract the path from the user's message
2. Use `defaults.model` from config
3. Execute immediately — no questions needed

### 3. No Path Given

User says something like:
- "ask the other project about the API"
- "I need info from the backend"

**Flow:**
1. Read `projects.json` and list registered projects via `AskUserQuestion`
2. Let the user pick a registered project OR type a custom path
3. Then execute

## Model Selection

The model is resolved in this priority order:

1. **User explicitly says it** → use that model
   - "ask backend **with opus** about the architecture"
   - "bridge to frontend **using haiku** — quick question"
2. **Project-level config** → `projects.<alias>.model` from `projects.json`
3. **Global default** → `defaults.model` from `projects.json`
4. **Hardcoded fallback** → `sonnet`

If the user says "use opus" or "with haiku", extract that and override everything else.

## Running a Query

### Step 1: Build the Prompt

Construct a clear, self-contained prompt for Agent B. Always include:
- What information is needed
- Relevant context from the current project (error messages, types, expected contracts)
- The desired response format

**Prompt template:**
```
You are analyzing this project to help a developer working in a separate [frontend/backend/service] project.

Context from the caller project:
---
[Insert relevant context: error message, type definition, API call code, etc.]
---

Task: [Clear, specific question or request]

Respond concisely. Focus only on what was asked.
```

### Step 2: Execute

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

# With edit capability (requires user confirmation first)
echo "<prompt>" | claude -p \
  --model <MODEL> \
  --output-format json \
  --permission-mode acceptEdits \
  --add-dir <TARGET_PROJECT_PATH> \
  2>/dev/null
```

**IMPORTANT:**
- Always append `2>/dev/null` to suppress stderr noise.
- Always use `--output-format json` for reliable parsing.
- Use `--add-dir` to grant the spawned agent access to the target project directory.
- For read-only queries, use `--permission-mode plan`.
- For edit tasks, use `--permission-mode acceptEdits` and confirm with the user first.

### Step 3: Parse the Response

The JSON output contains:
```json
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Agent B's text response",
  "session_id": "uuid-for-resumption",
  "total_cost_usd": 0.05,
  "duration_ms": 3000
}
```

Extract and present:
- `result` — the actual answer from Agent B
- `session_id` — save for potential follow-up
- `is_error` — check for failures

### Step 4: Present Results

Summarize Agent B's response. Include:
- The answer/analysis from the target project
- Session ID reference for follow-up: "You can continue this conversation by saying 'bridge resume' or asking a follow-up about [project alias]."

## Resuming a Session

To continue a previous cross-project conversation:

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

When resuming:
- Do NOT re-specify `--model`, `--permission-mode`, or `--add-dir` (inherited from original).
- Only pass `--resume`, `--output-format json`, and the new prompt.

User triggers resume by saying:
- "bridge resume — also check the middleware"
- "follow up with backend — what about pagination?"
- "ask backend again — show me the error handler too"

## Managing Projects

### Adding a project

When the user says "bridge add project" or "register project":
1. Ask for alias, path, description, and optional model override via `AskUserQuestion`
2. Read `projects.json`, add the new entry, write it back
3. Confirm to the user

### Listing projects

When the user says "bridge list" or "show bridge projects":
1. Read `projects.json`
2. Display a table of alias, path, description, model

### Removing a project

When the user says "bridge remove [alias]":
1. Read `projects.json`, remove the entry, write it back
2. Confirm to the user

## Quick Reference

| Scenario | Mode | Key Flags |
| --- | --- | --- |
| Ask about an API endpoint | read-only | `--permission-mode plan --add-dir <PATH>` |
| Debug a cross-project error | read-only | `--permission-mode plan --add-dir <PATH>` |
| Analyze dependencies/schemas | read-only | `--permission-mode plan --add-dir <PATH>` |
| Apply a fix in target project | edit | `--permission-mode acceptEdits --add-dir <PATH>` |
| Resume previous conversation | inherited | `--resume <SESSION_ID>` |
| Deep architectural analysis | read-only | `--model opus --permission-mode plan --add-dir <PATH>` |

## Common Scenarios

### 1. Frontend asks Backend about an endpoint

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

**Prompt to Agent B:**
```
You are analyzing this backend project to help a frontend developer.

Context from frontend:
---
I'm calling GET /api/users/:id but getting a 422 error.
My request code: fetch(`/api/users/${id}`, { headers: { Authorization: `Bearer ${token}` } })
---

Task: Find the route handler for GET /api/users/:id. What parameters does it expect? What validation does it apply? What does a successful response look like?
```

### 2. Debug a contract mismatch

**User says:** "bridge to backend — response shape doesn't match what we expect for user data"

**Prompt to Agent B:**
```
You are analyzing this backend project to help a frontend developer.

Context from frontend:
---
The frontend expects: { user: { id: string, name: string, email: string, avatar: string } }
But we receive: { data: { userId: number, fullName: string, emailAddress: string } }
---

Task: Find the serializer/response transformer for the user endpoint. Show the actual response structure and field names.
```

### 3. Check for breaking changes

**User says:** "ask backend with opus — did anything break for our user endpoints recently?"

### 4. Get TypeScript types from backend

**User says:** "ask backend with haiku — give me TypeScript interfaces for /api/auth/* endpoints"

## Error Handling

- If `claude -p` exits non-zero, report the error and ask whether to retry with different settings.
- If `is_error` is `true` in the JSON, show the error message and suggest adjustments.
- If the response is empty or malformed, check:
  1. Target project path exists and is accessible
  2. Model is available
- If `projects.json` doesn't exist or is invalid, create a fresh one with defaults and ask the user to register their first project.

## Safety Rules

- **NEVER** use `--dangerously-skip-permissions` on the spawned instance.
- **NEVER** use `--permission-mode bypassPermissions` without explicit user consent.
- Default to `--permission-mode plan` (read-only) unless edits are explicitly requested.
- Always confirm with the user before running in edit mode on another project.