Mobile Companion

The Mobile Companion Service enables secure, local-network mobile access to your entire Cairn workspace from any phone or tablet without cloud lock-in.

Connection & Setup

The companion service streams the Cairn web application over your local Wi-Fi network directly from your running desktop application. Because everything stays local, no internet connection is required.

Starting the Service

1. Open Cairn on your desktop and navigate to Settings → Mobile Access.
2. Toggle the switch to **Enable Network Access**.
3. A secure connection card will display:
   • Your desktop's local server IP address and port.
   • A scannable QR code encoding the server URL.
   • A randomly generated 4-digit **Single-use Login PIN**.

What a paired phone can do

Since Cairn 3.1.0, Mobile Access is limited to your workspace. A paired phone can read and edit notes, cards, Idea Flow and tags, chat with the agent, and browse code, diffs and git history. It can no longer run anything on your computer or change Cairn's setup: no terminals or shells, file edits in code folders, git commits, pushes or discards, MCP servers, plugins, sync, secrets, approval grants, AI provider and agent settings, automation edits or runs, or Mobile Access settings — do those from the desktop app.

Agent turns started from a paired phone follow your desktop's approval settings and saved AI connections. A phone cannot choose its own approval mode, and new coding sessions from it run only in the project's code directory, which can only be changed on the desktop.

Mobile UI Adaptations

Cairn automatically detects a mobile screen width and adjusts the application's layout to prioritize reading comfort, navigation, and visual clarity.

• Slide-over Sidebar Drawer: The project/workspace sidebar collapses into a slide-over panel. Swipe from the left screen edge or tap the menu icon to trigger it. A backdrop blur overlay dims the main workspace, which can be tapped to dismiss the drawer.
• Responsive Notes Editor: On smaller viewports, the notes editor list panel slides out of view while editing to maximize space. Note titles and metadata wrap dynamically, and back buttons are nested next to note controls for easy single-tap navigation.
• Fullscreen AI Chat: The AI Chat assistant expands to cover `100vw` / `100dvh`, hiding manual layout resize handles so you have plenty of room to formulate prompts.
• Horizontal Settings Category Strip: Settings navigation scales into a horizontal swipeable strip so you can navigate panels without layout stretching.
• Tabbed Agent Workspace: Absolute multi-pane panels in the Developer Agent Workspace collapse into touch-friendly tabstrips (Terminal, Files, Editor, Diff, Console).

Touch Interaction Parity

To replace mouse hover and right-click states, the companion implements touch-specific sensor loops across the canvas and board components:

Kanban Board Drag-and-Drop

Standard touch scrolling on a board can accidentally trigger drag states. To resolve this, Cairn utilizes a dedicated touch drag sensor:

• Cards and columns require a **250ms press-and-hold** gesture before they can be dragged.
• A small **5px movement tolerance threshold** prevents accidental drags during vertical scrolling.
• Card and column handles include CSS `touch-action: none` to cede control to the HTML5 DnD layer immediately on hold.

Idea Flow Canvas Gestures

Interactive nodes on the Idea Flow canvas are adapted for reliable touch navigation:

• Long-Press Canvas: Pressing and holding on empty canvas space for **350ms** triggers the node picker at that exact touch coordinate, replacing the desktop right-click menu.
• Single-Tap Nodes: Tapping a node displays the Node Editor modal. Double-tapping is disabled on touch viewports due to latency.
• Minimap Autohide: The floating navigation minimap is automatically hidden on touch screens to maximize viewport estate.
• Multi-touch Pan & Zoom: Seamless one-finger pan and pinch-to-zoom gestures allow you to traverse huge flow layouts.

PDF Export & Sharing Sheets

Exporting note content to PDF from mobile clients bypasses system print dialogues where possible:

• Tapping **Export to PDF** on a note compiles the document and applies an inline responsive print stylesheet (`@media print`) that removes headers, toolbars, and scroll zones.
• The compiled document is served to the native **Web Share API** (if supported by your device browser like Safari or Chrome), prompting the native system share sheet immediately to send, print, or save.
• If the Web Share API is unsupported, the browser falls back to a standard local file download.

Automated Sync & Live Updates

The companion utilizes Server-Sent Events (SSE) and local database triggers to sync client-state instantly:

• Config Syncing: a paired phone uses your desktop's saved AI connections, so you don't have to enter provider settings on mobile.
• Live Activity Updates: Any workspace modification (e.g., the AI coding agent editing a file, creating a card, or appending notes) broadcasts a `db:changed` packet. Connected mobile browsers refresh their visual board columns, and notes instantly in real-time.