Termopus Bridge

Lightweight desktop agent connecting Claude Code to your phone

---

Overview

The Termopus Bridge is a Rust agent that runs on your computer and acts as the secure intermediary between Claude Code and your phone. It sits in the menu bar, manages Claude sessions, encrypts all communication, and maintains persistent connections through a Cloudflare relay.

Core Modules

Stream-JSON Backend

Structured Claude CLI protocol parser using claude -p --output-format stream-json. Handles all event types from the Claude CLI:

• init — session initialization with model info
• text_delta — streaming text output
• message_delta — message completion with token usage
• tool_use — file edits, bash commands, search operations
• result — final session result with cost data
• thinking — extended thinking blocks

Session Loop

The main session lifecycle manager (~2,000 lines) handling:

• Resume & crash recovery — auto-detects orphaned sessions, resumes with fresh relay room
• Conversation catchup — sends last 20 messages when reconnecting
• Live state tracking — real-time status broadcast (Idle / Thinking / ToolUse / Respawning / Exited)
• Respawn limiter — max 3 auto-restart attempts with exponential backoff
• Native command handlers — Optimize Chat, Start Fresh, Statistics, Undo, Plan Mode

Permissions-Aware Hook System

3-tier permission engine that intercepts every Claude Code tool call:

┌─────────────────┐
│  Mode Override   │  ← "plan" mode blocks all writes
├─────────────────┤
│  Rule Matching   │  ← settings.local.json glob patterns
├─────────────────┤
│  Phone Fallback  │  ← send to phone for user decision
└─────────────────┘

• Atomic file IPC (write-to-tmp + rename)
• Auto-writes "Always Allow" glob rules (e.g., "Bash(git *)")
• Intercepts AskUserQuestion → renders as interactive card on phone

Crypto Module

• EC P-256 keypair generation
• ECDH key exchange with phone's hardware-backed keys
• AES-256-GCM encryption for all relay messages
• HKDF key derivation for session keys

GUI Mode

Desktop interface built with egui:

• Menu bar tray icon with session status
• QR code display for phone pairing
• Session list with right-click management
• Setup wizard for first-time configuration

Architecture

┌──────────────────────────────────────────────┐
│              Termopus Bridge                  │
│                                              │
│  ┌────────────┐     ┌─────────────────────┐  │
│  │ GUI (egui) │     │  Session Manager    │  │
│  │ Tray icon  │     │  Multi-session      │  │
│  │ QR display │     │  Crash recovery     │  │
│  └─────┬──────┘     └──────────┬──────────┘  │
│        │                       │              │
│  ┌─────┴───────────────────────┴──────────┐  │
│  │          Session Task Loop             │  │
│  │  Stream-JSON ↔ Crypto ↔ Relay WS      │  │
│  └─────┬──────────────────────────┬───────┘  │
│        │                          │           │
│  ┌─────┴──────┐           ┌──────┴────────┐  │
│  │ Hook System│           │ File Transfer │  │
│  │ 3-tier     │           │ Chunked E2E   │  │
│  │ Permissions│           │ Session-scoped │  │
│  └────────────┘           └───────────────┘  │
└──────────┬───────────────────────┬───────────┘
           │ stdio                 │ WebSocket
     ┌─────┴─────┐         ┌──────┴──────┐
     │Claude Code│         │  CF Relay   │
     └───────────┘         └─────────────┘

Binaries

Binary	Purpose
termopus	Main bridge agent — GUI, sessions, relay
termopus-hook	Claude Code hook handler — standalone binary for 3-tier permission engine

Tech Stack

Component	Technology
Language	Rust (2021 edition)
Async Runtime	Tokio
WebSocket	tokio-tungstenite
GUI	egui + eframe
Crypto	aes-gcm, p256, hkdf, x25519-dalek
CLI Interface	Stream-JSON protocol
HTTP	reqwest (rustls-tls)

---

termopus.com