How It Works

This page explains the technical architecture of the Mirra Claude Code Bridge for developers who want to understand how it works under the hood.

Architecture overview

┌────────────────────────────────────────────────────────────────────────┐
│                              YOUR PC                                    │
│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐  │
│  │  Claude Code    │────►│  Claude Hooks   │────►│  Mirra Bridge   │  │
│  │  (Terminal)     │     │  (Notification) │     │                 │  │
│  └─────────────────┘     └─────────────────┘     └────────┬────────┘  │
│           ▲                                               │            │
│           │ stdin                                         ▼            │
│  ┌────────┴────────┐                          ┌─────────────────┐     │
│  │  Session        │◄─────────────────────────│  Mirra SDK      │     │
│  │  Manager        │                          │                 │     │
│  └────────┬────────┘                          └────────┬────────┘     │
│           │                                            │              │
│           └───────────────────┬────────────────────────┘              │
│                               │                                        │
│                    ┌──────────┴──────────┐                            │
│                    │  Mirra Bridge       │                            │
│                    │  Server             │                            │
│                    └──────────┬──────────┘                            │
│                               │                                        │
└───────────────────────────────┼────────────────────────────────────────┘
                                │
                                │ Mirra Tunnel
                                ▼
┌────────────────────────────────────────────────────────────────────────┐
│                           MIRRA CLOUD                                   │
│  ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐  │
│  │  Mirra          │────►│  Mirra Flow     │────►│  Mirra Router   │  │
│  │  Messaging      │     │  (session       │     │                 │  │
│  │                 │     │   matching)     │     │                 │  │
│  └────────┬────────┘     └─────────────────┘     └────────┬────────┘  │
│           │                                               │            │
│           ▼                                               │            │
│  ┌─────────────────┐                                      │            │
│  │  Mirra          │              Routes reply back ──────┘            │
│  │  Notifications  │              to your PC                           │
│  └────────┬────────┘                                                   │
│           │                                                            │
└───────────┼────────────────────────────────────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          MIRRA APP                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │  Structured Data Cards                                              ││
│  │  ┌───────────────────┐  ┌─────────────────────────────────────┐    ││
│  │  │ Permission Cards  │  │ Execution Detail Cards              │    ││
│  │  │ [Allow] [Deny]    │  │ ✓ Read file.ts                      │    ││
│  │  │ [Allow Always]    │  │ ✓ Bash: npm install                 │    ││
│  │  └───────────────────┘  │ ⊘ AskUserQuestion (skipped)         │    ││
│  │                         └─────────────────────────────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────┘

Component breakdown

Mirra Tunnel

A secure WebSocket connection between your PC and Mirra Cloud. The tunnel:

Authenticates using your Mirra API key
Proxies HTTP requests from Mirra Cloud to your local bridge server
Reconnects automatically if the connection drops
Requires no external accounts — everything uses your existing Mirra credentials

When the bridge starts, it establishes the tunnel and receives a unique URL that Mirra Cloud uses to reach your PC.

Claude Code hooks

Claude Code supports hooks that run commands on specific events. The bridge configures two hooks in ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "command": "mirra-cc-bridge hook notification"
      }
    ],
    "Stop": [
      {
        "command": "mirra-cc-bridge hook stop"
      }
    ]
  }
}

Notification hook — Fires when Claude needs user input (permission prompts) or has updates
Stop hook — Fires when a Claude Code session ends

Mirra Bridge Server

A local server on your PC that:

Receives incoming requests from Mirra Cloud via the tunnel
Manages Claude Code session lifecycle
Handles permission responses and user input
Sends structured data to the Mirra app

Session Manager

Handles the lifecycle of Claude Code processes:

Spawns sessions with environment variables for Mirra integration
Creates Mirra Flows for reply routing
Tracks active sessions (up to 5 concurrent)
Supports multi-turn conversations using Claude's --resume flag

Mirra Flow

Each session creates a Flow that routes replies back to the correct session:

// Flow configuration (simplified)
{
  trigger: {
    type: 'event',
    eventSource: 'mirra',
    conditions: [
      { field: 'mirra.replyTo.automation.sessionId', equals: sessionId }
    ]
  },
  action: 'route to Mirra Router'
}

When you reply to a Claude Code message, the Flow matches your reply to the session and triggers the router.

Mirra Router

A lightweight script that forwards replies to your PC. When triggered:

Extracts the reply text and session ID
Calls your PC's bridge server via the tunnel
Bridge sends the input to Claude Code's stdin

This is much cheaper than having Mirra's AI process each reply — Flows trigger instantly on matching messages.

Event flows

Sending output (PC → Phone)

Claude Code generates output or needs approval
Notification hook fires with event data
Bridge formats the output as structured data
Mirra SDK sends message with structured data attached
Mirra delivers notification to your phone
App renders the message with rich cards

Receiving replies (Phone → PC)

You reply to a Claude Code message or tap a permission button
Mirra creates a MIRRA_MESSAGE event
Mirra Flow matches the reply to the session
Mirra Router executes
Router calls your PC's bridge server via tunnel
Bridge sends input to Claude Code's stdin
Claude Code processes your reply

Permission responses

When you tap a permission button, the bridge translates it to stdin input:

Button	Stdin
Allow	`y`
Allow Always	`a`
Deny	`n`

Structured data

The bridge sends two types of structured data to the Mirra app:

Permission prompt cards

When Claude needs approval:

{
  displayType: 'list',
  templateId: 'cc_permission_prompt',
  items: [
    { id: 'allow', title: 'Allow', icon: 'checkmark-circle' },
    { id: 'allow_always', title: 'Allow Always', icon: 'checkmark-circle-outline' },
    { id: 'deny', title: 'Deny', icon: 'close-circle' }
  ],
  metadata: {
    sessionId: 'cc_session_...',
    promptType: 'tool_approval',
    tool: 'Bash'
  }
}

Execution detail cards

When Claude completes work:

{
  displayType: 'card',
  templateId: 'execution_details',
  data: {
    title: 'Execution Details',
    badges: ['3 steps', 'Bash: 1, Read: 2'],
    steps: [
      { title: 'Read: package.json', status: 'success', icon: 'document' },
      { title: 'Run: npm install', status: 'success', icon: 'terminal' },
      { title: 'Edit: src/index.ts', status: 'success', icon: 'code' }
    ],
    summary: { Bash: 1, Read: 1, Edit: 1 }
  }
}

Step statuses:

success — Tool completed without error
error — Tool failed
skipped — Interactive tool not available in remote mode (e.g., AskUserQuestion)

Session continuity

The bridge supports multi-turn conversations using Claude Code's --resume flag:

First prompt spawns a new Claude Code process
Claude generates a session_id for its conversation
Bridge stores the mapping: bridge_session_id → claude_session_id
Follow-up prompts spawn new processes with --resume {claude_session_id}
Claude continues with full conversation context

This allows natural back-and-forth conversations without losing context.

Security considerations

The bridge server accepts requests from Mirra Cloud via the tunnel. Your API key authenticates the tunnel connection, but anyone with access to your Mirra account can control sessions on your PC.

Credential security

API keys are generated automatically during browser authentication
Keys are stored in ~/.mirra/cc-bridge.json with restricted permissions
Never commit your config file to version control
Re-run mirra-cc-bridge setup if you suspect credentials are compromised

Session isolation

Each session has a unique ID and its own Flow. Sessions cannot interfere with each other's message routing.

Tunnel security

The tunnel uses secure WebSocket (WSS)
Authentication happens on connection using your API key
Failed auth attempts are rejected immediately

Performance

The architecture is designed for efficiency:

No AI calls for routing — Flows match events directly
Sub-second latency — Replies reach your PC almost instantly
Automatic cleanup — Flows are deleted when sessions end
Lightweight — The bridge uses minimal resources when idle

Extending the bridge

The bridge is open source. Common extensions:

Custom formatting — Modify how output appears on mobile
Additional hooks — Capture more Claude Code events
Metrics — Track session duration, message counts, etc.
Custom structured data — Add new card types for your use case

How It Works

On this page