// what it is
One command on your dev box.
cordless is a single self-contained binary you install on your dev box or laptop. Run
cordless and it opens a full-screen terminal dashboard whose starting
screen is a pairing QR — scan it with the phone app and your sessions (a shell,
claude, codex, copilot, or your own custom launchers)
are in your pocket. Organise them into tab groups, rename tabs, and keep going after a
reboot — sessions are restored with their scrollback history. The daemon stays up after
you close the dashboard, and reconnecting replays exactly where you left off.
// features
Built for people who live in the terminal.
CLI-first
One self-contained binary — its own Node runtime and node-pty, no install prereq. Run cordless for a full-screen dashboard: status, a live pairing QR, and your sessions.
Attention state
Juggling many agents? cordless infers which is working, idle, or waiting for you from its output, badges and sorts them attention-first, and can ping your phone (ntfy / webhook).
Persistent sessions
PTYs survive disconnects, network switches, and app backgrounding. Reconnect and it replays from your last-seen byte, or a full-screen snapshot.
Tabs & groups
From the dashboard press o to open a session in a new terminal tab (Windows Terminal) — like browser tabs. Chrome-mobile-style groups keep >10 sessions tidy on the phone.
Reach it anywhere
Tailscale is the recommended path; same-Wi-Fi LAN also works. No ports exposed to the public internet — ever.
Secure by default
Per-device hashed tokens, single-use pairing codes only the local daemon can mint (loopback-only), an Origin allowlist, strict CSP — and a daemon that only ever runs as you.
// changelog
What's new.
Reliable start & built-in help
cordless start detaches cleanly in every environment (plain shell, Chocolatey shim, or CI). And cordless documents itself: cordless help <command> shows usage, options, and examples for anything.
Agent icons + a scrollable key bar
The app shows each agent as a colored icon (shell, Claude, Codex, GitHub Copilot) instead of a name, and the on-screen key bar scrolls so Esc/Tab/arrows/^C are all reachable. Open a session in a new tab with o.
Tab groups, custom launchers, rename
Chrome-mobile-style groups, your own profiles in ~/.cordless/config.json (any command/args/cwd/env), and live rename from the dashboard e key or a long-press on the phone.
Persisted scrollback history
A capped, plain-text scrollback is saved per session, so a reopened session after a reboot shows what it was doing before — cordless history to inspect or clear it.
// install
Two commands. Thirty seconds.
Have Node? npx cordless-cli. Prefer zero dependencies? Grab the self-contained binary. Either way, cordless shows a QR you scan with the phone.
$ npx cordless-cli # try it instantly — no install $ npm i -g cordless-cli # or install the `cordless` command globally $ cordless # dashboard + a pairing QR
No Node? Grab the self-contained binary below — it bundles its own Node runtime and
node-pty, so there's nothing to install first.
Install cordless on your dev box
Download the self-contained cordless CLI from Releases — it bundles its own Node runtime and node-pty, so there's nothing to install first.
Windows cordless-cli-windows-x64.zip → run cordless.exe Linux cordless-cli-linux-x64.tar.gz → run ./cordless macOS use the desktop app, or build from source
Then let cordless install itself in one step:
$ cordless setup # copy to a stable path, add to PATH + autostart, START the daemon $ cordless # open the dashboard: status + a pairing QR + your sessions $ cordless install # (alt) just register the daemon to run at login
cordless setup is the whole installer: it copies the binary, adds it to PATH, registers autostart, cleans up any older install, and starts the daemon. Open a new terminal and run cordless.
Pair your phone
cordless's starting screen shows a QR. Install the Android app, tap Scan QR, and scan it. (Or press p for a fresh code, run cordless pair, or open the printed URL in your phone's browser as a PWA.)
From anywhere
Put the dev box and phone on the same Tailscale tailnet and lock port 7443 to your own devices with a tailnet ACL. The pairing QR then uses a stable 100.x / *.ts.net address. Never expose 7443 to the public internet.
Manage it: cordless status · cordless doctor · cordless sessions ·
cordless attach <id> · cordless resume · cordless profiles ·
cordless group · cordless rename <id> <title> · cordless history ·
cordless notify test · cordless stop.
Prefer to run from source? (Node 22+)
$ git clone https://github.com/naveenneog/cordless $ cd cordless $ npm run setup # installs agent + client deps (builds node-pty) $ npm run build # builds the web client the daemon serves $ npm start # daemon on :7443 — then `node agent/src/index.js` for the dashboard $ npm --prefix agent run sea # build a self-contained binary into agent/dist-sea/
// requirements
Basically nothing.
Dev box (runs cordless)
Nothing for the self-contained binary (its own Node runtime + node-pty, Windows or Linux) — or Node ≥ 20 for npx cordless-cli. Optional: coding agents on PATH (claude, codex, copilot), or your own launchers.
Phone
Any modern browser (install the PWA), or Android 8.0+ for the APK. Nothing else to install.
Remote access (optional)
Tailscale on the dev box and phone for secure access from anywhere. Same-Wi-Fi LAN needs nothing extra.
Building from source
Only if you build it yourself: Node ≥ 22 and a C/C++ toolchain for node-pty; for the APK, add JDK 21 + the Android SDK. Most people just grab the prebuilt binaries.
// desktop
A window over the same daemon.
The CLI is the primary way to run cordless — the desktop app is a thin, hardened Electron
window over the same local daemon the CLI runs, so install the CLI first
(cordless setup). Same sessions, tabs, groups, and replay as the phone — with a real keyboard.
If it opens to a "daemon isn't running" screen, it finds your installed CLI and offers to start it.
QR-first auth
Pairing stays QR/code based. The desktop adds one 🖥️ Connect to this computer button backed by a loopback-only credential.
Loopback only
That credential lives in ~/.cordless/desktop-credential.json (mode 0600) and is rejected for any non-loopback address — even a Tailscale IP.
Never a blank window
If the daemon is down, the app shows a Start daemon / Retry screen instead of failing silently.
Grab an installer from Releases
(Windows .exe, macOS .dmg, Linux .AppImage/.deb).
// on your phone
The whole terminal, one thumb.
