Claude Bridge Setup

---
name: claude-bridge-setup
description: Guide the user through activating claude-bridge live-data hooks in ~/.claude/settings.json. Use when the user asks how to install the plugin's statusLine wrapper or PostToolUse refresh-limits hook, or when peer_context_status / rate_limit_status returns `hasLiveData: false` with a setupPointer. Triggers — "setup live data", "install claude-bridge hooks", "hasLiveData false", "how do I activate statusLine wrapper", "setupPointer says", "peer_context_status returns no data".
---

# claude-bridge-setup — Live-data activation

The v0.9.0+ live-data architecture requires **two** additions to `~/.claude/settings.json`:

1. **statusLine wrapper** — writes CC per-render stdin JSON to `~/.claude-bridge/live/statusline.json`. Optional passthrough to user's original statusLine.
2. **PostToolUse hook** — calls Anthropic OAuth `/api/oauth/usage` (throttled ~1/min) as fallback rate-limits source. Writes to `~/.claude-bridge/live/oauth-api.json`.

Without at least one, `peer_context_status` and `rate_limit_status` return `hasLiveData: false` with a `setupPointer`.

## Auto-setup path (recommended)

The plugin's **bundled SessionStart hook** (`setup-check.cjs`) does most of this for you:

- Detects the newest installed plugin version in cache dir
- Refreshes stable symlinks at `~/.claude/claude-bridge-{statusline,refresh-limits}.cjs`
- Auto-generates a wrapper script at `~/.claude/claude-bridge-statusline-wrapper.sh` that preserves any pre-existing statusLine command as passthrough
- Prints a banner on stderr with copy-paste snippets when setup is incomplete

If you saw a banner starting with `━━━ claude-bridge vX.Y.Z setup ━━━`, follow its instructions. Otherwise apply the manual steps below.

## Manual setup

### Step 1 — statusLine wrapper

Edit `~/.claude/settings.json`:

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/claude-bridge-statusline-wrapper.sh"
  }
}
```

The wrapper script is auto-generated by the plugin's SessionStart hook on first run. If it doesn't exist yet, restart Claude Code once, then verify with:

```bash
cat ~/.claude/claude-bridge-statusline-wrapper.sh
```

### Step 2 — PostToolUse hook

Add to the same `settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "command": "node ~/.claude/claude-bridge-refresh-limits.cjs",
        "timeout": 6
      }]
    }]
  }
}
```

If PostToolUse already exists in your settings.json, **merge into the existing array** — don't replace.

### Step 3 — restart Claude Code

Symlinks and wrapper script take effect at next SessionStart. Verify with:

```
peer_context_status
```

Expected: `hasLiveData: true`, `contextLimitSource: "statusline-stdin"`, `model: "..."`, `effortLevel: "..."`.

```
rate_limit_status
```

Expected: `source: "statusline-stdin"` (or `oauth-api` after ~1 minute of tool activity), `staleness: "fresh"`.

## Passthrough to your existing statusLine

If you had a status line before installing claude-bridge (e.g. [benabraham/claude-code-status-line](https://github.com/benabraham/claude-code-status-line)), setup-check captures the original command from your settings.json on first run and preserves it via `CLAUDE_BRIDGE_UNDERLYING_STATUSLINE` env var. The wrapper script sets this env var then execs the plugin's `statusline.cjs`, which spawns your original as subprocess and streams its stdout back. Native rendering unchanged.

You can override the detected command by editing `~/.claude/claude-bridge-statusline-wrapper.sh` (setup-check will not overwrite manual edits — it only regenerates when the file's auto-generated marker is present).

## Troubleshooting

**Banner shows on every SessionStart even though I completed setup.**
Setup-check compares `settings.json.statusLine.command` and `hooks.PostToolUse[*].hooks[*].command` for substring matches on `claude-bridge-statusline` / `claude-bridge-refresh-limits`. If your paths differ (e.g. absolute path to the cache dir instead of the symlink), setup-check doesn't recognize them. Switch to the symlink paths above.

**`peer_context_status` still returns `hasLiveData: false` after setup.**
- Did Claude Code render a statusLine since you configured it? StatusLine renders on session start, first user prompt, and periodically. Send any prompt — even "hi" — to trigger a render.
- Are the symlinks pointing at a valid cache dir? `ls -la ~/.claude/claude-bridge-*.cjs` should show two links resolving to `.../plugins/cache/claude-bridge/claude-bridge/<version>/servers/claude-bridge/dist/`.

**`rate_limit_status` shows `source: "statusline-stdin"` but no `spend` / `perModelWeekly` fields.**
StatusLine stdin only carries the basic session + week utilization. Rich fields come from the OAuth API path. Wait until the PostToolUse hook fires (up to ~1 minute after your next tool call), or trigger a tool call now.

**OAuth path never fires (no `oauth-api.json` in `~/.claude-bridge/live/`).**
- Is `~/.claude/.credentials.json` present with `claudeAiOauth.accessToken`? On macOS this is stored in Keychain instead — check `security find-generic-password -s "Claude Code-credentials"`.
- Does `curl https://api.anthropic.com/api/oauth/usage` work from your machine? Corporate proxies may block it.

## Removing the setup

To roll back to the original statusLine and disable the hook, restore your `~/.claude/settings.json` from before installation. Symlinks and wrapper script under `~/.claude/claude-bridge-*` can be safely deleted — the plugin won't recreate them if you subsequently uninstall it via `/plugin uninstall`.