> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/yocxy2/claurst/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridge mode

> Connect Claurst to the claude.ai web UI or IDE extensions for remote control and live collaboration.

Bridge mode creates a JWT-authenticated bidirectional connection between your local Claurst process and the claude.ai web UI or IDE extensions. Once connected, you can drive the CLI session from a browser tab, share diffs live with your IDE, and sync file selections between your editor and Claude.

Bridge mode is gated behind the `BRIDGE_MODE` compile-time feature flag and requires a claude.ai subscription.

## Enabling bridge mode

Start a bridge session using the `/bridge` or `/rc` slash command from within an active Claurst session:

```
/bridge
```

or use the standalone remote-control command:

```bash theme={null}
claude remote-control
```

## Work modes

The standalone bridge supports three session spawn modes, configured via `BridgeConfig.spawnMode`:

| Mode             | Behavior                                                               |
| ---------------- | ---------------------------------------------------------------------- |
| `single-session` | One session; the bridge tears down when it ends                        |
| `worktree`       | Persistent server; each incoming session gets an isolated git worktree |
| `same-dir`       | Persistent server; sessions share the working directory                |

`worktree` mode is the safest option for multi-session use — each session gets its own isolated git worktree so concurrent sessions cannot conflict.

## Transport options

The bridge crate supports three transport implementations:

| Transport            | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `SSETransport`       | Server-Sent Events over HTTP — used for CCR v2 sessions                          |
| `WebSocketTransport` | Full-duplex WebSocket — default for `ws://` URLs                                 |
| `HybridTransport`    | WebSocket for reads, HTTP POST for writes — batches stream events before posting |

Transport selection is automatic based on the session URL scheme and environment configuration. The `HybridTransport` accumulates `stream_event` messages for up to 100ms before posting them as a batch, which reduces request overhead during high-throughput streaming.

## IDE integration

VS Code and JetBrains extensions connect to Claurst via direct-connect. Once connected:

* **Live diff viewing** — file changes made by Claude appear in your IDE's diff viewer as they happen
* **File selection sync** — selecting files in your IDE forwards them to Claude as context
* **Status indicator** — your IDE shows a status badge reflecting the current bridge connection state (`ready`, `connected`, `reconnecting`, `failed`)

The IDE extensions connect to the local direct-connect server started by Claurst's bridge initialization. No cloud relay is involved for the IDE connection itself.

## JWT authentication

Every bridge API call is authenticated with a JWT. The `cc-bridge` crate's `jwt` module decodes the payload without signature verification to read the `exp` claim, and the `createTokenRefreshScheduler` proactively schedules token refreshes 5 minutes before expiry.

On token expiry:

* **V1 sessions**: the new OAuth token is injected directly to the child process stdin
* **V2 sessions**: `reconnectSession` is called to trigger server re-dispatch with a fresh JWT (V2 validates the `session_id` JWT claim directly)

## Trusted device tokens

When the `tengu_sessions_elevated_auth_enforcement` gate is active, bridge API requests include an `X-Trusted-Device-Token` header. This token is derived from a SHA-256 hash of device-identifying information (hostname, username, home directory path) and enables elevated security tiers for persistent bridge registrations.

The device fingerprint is computed in the `trusted_device` module of `cc-bridge`:

```rust theme={null}
// Collects hostname + USER env var + home directory path
// SHA-256 hash → first 16 chars of lowercase hex
device_fingerprint() -> String
```

## KAIROS mode

KAIROS is an always-on proactive assistant mode, gated behind the `PROACTIVE` / `KAIROS` compile-time feature flags. When active, Claurst does not wait for you to type — it watches, logs, and proactively acts on things it notices.

<Warning>
  KAIROS is an internal Anthropic feature and is absent from external builds. It is documented here for completeness in the Claurst specification.
</Warning>

### How KAIROS works

KAIROS maintains **append-only daily log files** at `~/.claude/memory/logs/YYYY/MM/YYYY-MM-DD.md`. It writes observations, decisions, and actions throughout the day.

On a regular interval, Claurst sends `<tick>` prompts to Claude, which then decides whether to act proactively or stay quiet. The tick system has a **15-second blocking budget** — any proactive action that would block your workflow for more than 15 seconds is deferred. This keeps KAIROS helpful without being disruptive.

When KAIROS is active, responses use **Brief mode**: extremely concise output designed for a persistent assistant that should not flood the terminal.

### KAIROS-exclusive tools

| Tool               | What it does                                               |
| ------------------ | ---------------------------------------------------------- |
| `SendUserFile`     | Push files directly to the user (notifications, summaries) |
| `PushNotification` | Send push notifications to the user's device               |
| `SubscribePR`      | Subscribe to and monitor pull request activity             |

These tools are only available when the `PROACTIVE`/`KAIROS` feature flag is enabled.

## ULTRAPLAN

ULTRAPLAN offloads complex planning tasks to a remote Cloud Container Runtime (CCR) session running Opus 4.6, giving it up to 30 minutes to produce a deep plan.

<Info>
  ULTRAPLAN is an internal Anthropic feature gated behind additional compile-time flags and is absent from external builds.
</Info>

### How ULTRAPLAN works

<Steps>
  <Step title="Task identification">
    Claurst identifies a task that requires deep, extended planning beyond what is practical in a local session.
  </Step>

  <Step title="Remote session spin-up">
    A remote CCR session is created using the `tengu_ultraplan_model` config, running Opus 4.6.
  </Step>

  <Step title="Polling">
    Your terminal enters a polling state, checking every **3 seconds** for the planning result. Meanwhile, a browser-based UI lets you watch the planning happen and approve or reject the output.
  </Step>

  <Step title="Result delivery">
    When the remote plan is approved, the sentinel value `__ULTRAPLAN_TELEPORT_LOCAL__` is used to return the result to your local terminal, continuing the session with the completed plan in context.
  </Step>
</Steps>