Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt

Use this file to discover all available pages before exploring further.

Start a task on your computer, walk away, and check on your agents from your phone. See who’s working, who’s idle, who needs input. Send messages, answer questions, resume sessions — all from a chat-style interface on your phone. No account, no app install. Scan a QR code and you’re connected. End-to-end encrypted — the relay server never sees your code, prompts, or output.

​
How It Works

Your phone connects to your desktop CliDeck through a lightweight relay: 
Phone ←→ Relay (Cloudflare) ←→ Desktop CliDeck
              (encrypted,
            can't read anything)
  1. Your desktop runs CliDeck as usual with your agent sessions
  2. The relay forwards encrypted messages between your phone and desktop — it never decrypts them
  3. Your phone opens a web app that shows your sessions in a chat-like interface
The relay is a Cloudflare Worker that passes encrypted blobs between two WebSocket connections. It doesn’t store anything. When you disconnect, the room is gone.

​
Security

Mobile Remote uses end-to-end encryption (E2E). Here’s what that means in practice:
WhatWho can see it
Your prompts and codeOnly your phone and your desktop
Agent responsesOnly your phone and your desktop
Session names and statusOnly your phone and your desktop
Anything at allNot the relay. Not CliDeck’s servers. Nobody else.
How the encryption works:
  • When you pair, your desktop and phone each generate a cryptographic key pair (ECDH P-256)
  • They exchange public keys through the relay to derive a shared secret
  • All messages after that are encrypted with AES-256-GCM — the same standard used by Signal and WhatsApp
  • The relay only sees encrypted blobs. It cannot decrypt them. Even if someone intercepted the traffic, they couldn’t read it
The pairing URL (in the QR code) contains your desktop’s public key in the URL fragment — the part after # that browsers never send to the server. The relay never sees it.
CliDeck is a local tool. Mobile Remote doesn’t change that. Your code, prompts, and agent output stay between your devices. The relay is just a dumb pipe.

​
Getting Started

Mobile Remote is built into CliDeck. No separate app to install.
1

Have active sessions

Mobile Remote shows your existing sessions — it doesn’t create new ones. Launch one or more agent sessions in CliDeck first.
2

Click the mobile icon

In the CliDeck sidebar, click the phone icon in the navigation rail. A modal opens.
3

Install (first time only)

The first time you use Mobile Remote, CliDeck installs the clideck-remote package automatically. Click Add to CliDeck and wait a few seconds.
4

Scan the QR code

A QR code appears. Scan it with your phone’s camera. A web app opens in your phone’s browser — no app store download needed.
5

You're connected

Your phone shows all your active sessions. Tap one to see the conversation and start interacting.
You can also copy the pairing link and open it manually on any device with a browser.

​
What You Can Do From Your Phone

Once paired, your phone shows a session list grouped by project — similar to a chat app.

​
View sessions and status

Each session shows its name, agent icon, last message preview, and a live working/idle indicator. You can see at a glance which agents are done and which are still thinking.

​
Send messages

Tap a session to open it. Type a message and hit send — it goes straight to the agent’s terminal, as if you typed it on your keyboard.

​
Answer agent questions

When an agent presents a choice menu (like “Yes / No / Yes to all”), the menu appears as tappable buttons on your phone. No need to type — just tap your choice.

​
Resume previous sessions

Saved sessions from previous CliDeck runs appear in a separate section. Tap to resume them.

​
Close sessions

Swipe or use the session menu to close a session from your phone.

​
What You Can’t Do (Yet)

  • Create new sessions — You can only interact with sessions that already exist on your desktop. Start sessions from CliDeck on your computer first.
  • Multiple phones — One phone connection at a time per CliDeck instance.

​
Desktop Lock Screen

While your phone is connected, CliDeck shows a lock screen overlay on your desktop. This blurs the terminal content and blocks keyboard input — so if you’re away from your desk, nobody can see your sessions or type into them. The lock screen shows:
  • Connection time
  • Number of active sessions
  • A Disconnect button to end the session
When your phone disconnects (close the browser tab or navigate away), the lock screen lifts automatically and your desktop returns to normal.

​
Free Tier

Mobile Remote is free with one limit: one active session at a time. If you tap a different session while one is open, your current session closes first. A confirmation prompt lets you know before switching. You can check “Don’t show again” to switch silently.

​
Disconnecting

To end a mobile session:
  • From your phone — Close the browser tab
  • From your desktop — Click Disconnect on the lock screen, or click the mobile icon in the sidebar and disconnect from the modal
Once disconnected, the relay room is destroyed. Your pairing QR code is single-use — pair again next time with a fresh QR code.

​
Troubleshooting

​
QR code not appearing

  • Make sure clideck-remote installed successfully. Check the mobile icon modal for error messages.
  • Try clicking the mobile icon again to retry pairing.

​
Phone can’t connect

  • Make sure your phone has internet access.
  • The QR code is single-use. If you’ve already scanned it once and disconnected, click the mobile icon to generate a fresh one.

​
No sessions showing on phone

  • Mobile Remote only shows sessions that are already running on your desktop. Create at least one session in CliDeck first.
  • If you just started CliDeck, wait for the agent to initialize before pairing.

​
Status not updating on phone

  • Make sure telemetry is configured for your agents. Without telemetry, CliDeck can’t detect working/idle status — and that means your phone can’t show it either.