About
Terminal Deck is a window for running coding agents. It does not replace Claude Code, Codex CLI or Gemini CLI — it runs the real binaries and puts a workspace around them, so you can see which one is working, which one is stuck, and what the day has moved — and reach any of it from your phone when you are not at the desk.
It is free, MIT-licensed, developed in the open, and built by one person.
Why it exists
Running one agent in one terminal tab is fine. Running four is not, and four is where this gets interesting — one refactoring the API, one on the front end, one writing tests, one you started an hour ago and forgot.
At that point the terminal stops helping. Tab titles say zsh. You cannot
tell from outside a tab whether a session is mid-thought or has been sitting on a
yes/no question for twenty minutes, so you cycle through them to check — which is the
opposite of running things in parallel. You have no idea which one has quietly eaten
its context window, or moved ten times the tokens of the others, until something
breaks. And when you want to see what an agent actually said three sessions ago, the
scrollback is gone.
None of that is a modelling problem or a prompting problem. It is a workspace problem, and it is solvable with software that watches the sessions you already run.
So: sessions in tabs with a dot that tells the truth about each one; token and context usage read from the transcripts the agent already writes; a browser next to it so the thing being built and the thing building it are one keystroke apart; panels for git, files, artifacts, GitHub, MCP, hooks and readiness, so that checking any of them is not a reason to leave the window; and a phone or browser that attaches to the same sessions from anywhere, with nothing to set up but a six-digit code.
What it is built to
Four rules, applied to code rather than printed on a wall. Each one has a consequence you can see in the app — and a cost, which is the part worth stating.
Local-first
Every number this app shows comes from a file already on your machine. Usage,
context, the inspector and session search all read the JSONL transcripts
the agent writes; the MCP inspector reads the configuration you already have; the
GitHub panel shells out to your own gh. Nothing is uploaded, mirrored
or indexed elsewhere.
The consequence: there is no account, no server and no service to go down. If this project were abandoned tomorrow, the copy on your disk keeps working, because it never depended on anything but your disk.
No telemetry
No analytics, no usage events, no crash reporter, no first-run ping. Two sockets exist and both are named on the privacy page: a loopback endpoint for agent hooks to report to, and an outbound connection to the relay, held open from launch so a paired phone has something to attach to, which carries ciphertext it holds no key for and can be switched off in the Remote panel. The update check fetches a public file on GitHub the way a browser would, with no identifier of any kind attached, and nothing is downloaded or installed unless you press the button.
The consequence: the developer has no usage data. Which features are worth keeping is a question that has to be asked out loud, in the issue tracker, rather than inferred from a dashboard. That is a real cost, accepted on purpose. The privacy page spells all of it out.
Honest empty states
A panel with nothing in it should say which of the several possible nothings it is.
The GitHub panel distinguishes "gh is not installed" from "you are not
signed in" from "this folder has no GitHub remote", and shows the command that fixes
each. The alerts panel needs positive evidence for every rule it fires, so a
brand-new project is silent — a panel that cries wolf on day one is ignored by day
two.
The consequence: the app is wordier than a prettier one would be, and you never have to guess whether a blank panel means "nothing to show" or "something broke".
Never claim a capability the code lacks
The update button in Settings → Help says what this build can actually do rather than spinning and telling you that you are up to date, and the one artifact that cannot replace itself says so instead of offering. Accounts isolate Claude Code and Codex logins because both were verified against the real CLI; Gemini is listed and refused, with the reason on the row, rather than given a plausible-looking switch that silently shares a login. The app shows no price at all, because the one it could compute would mislead a subscriber and the one that would not cannot be computed. Usage and context are Claude Code only, and say so, because the transcripts they read are Claude Code’s.
The consequence: this site is smaller than it could be. Nothing on it describes something the code does not do, and where a feature has a limit, the limit is next to it.
How it is built
Electron, React and TypeScript. The main process owns every terminal process and every
piece of filesystem access; a single preload is the only bridge between it and the
interface. Sessions are real pseudo-terminals running the real CLI binaries, spawned
with your login shell's PATH, because a GUI app on macOS otherwise cannot
see a claude installed by nvm or Homebrew.
One working rule shaped more of this codebase than any architectural decision:
check it against something real before writing code that depends on it.
The prompt glyph a CLI draws is ❯ and not >. One API
request emits many transcript lines with the usage repeated, so the naive sum is
wrong. A cache write in a long session is billed at the one-hour rate, not the
five-minute one — assume otherwise and the cached portion of a session is
under-reported by more than a third. Cookies moved out of the directory the
documentation names. Every one of those was discovered by looking, and each would
otherwise have shipped as a confident wrong number.
The other rule: compiling is not working. A clean typecheck and a silent console have both, more than once, sat behind a window that was visibly wrong. Anything visible gets looked at before it is called done.
Every line here was written for this project. Where a feature matches something else on the market, that is because the underlying problem has one sensible answer — no code, components, stylesheets or artwork were taken from anyone.
Who makes it
Terminal Deck is built by Asad Iqbal. It started as a tool for his own work — several agents running at once across several projects, and no good way to see what any of them were doing — and it is released because that problem is not unique.
It is a single-maintainer project given away for free. There is no company behind it, no support desk and no roadmap commitment; the terms say so plainly rather than implying otherwise. Issues and pull requests are welcome at github.com/asadev/terminaldeck.
This project is not affiliated with, endorsed by or sponsored by Anthropic, OpenAI, Google, GitHub or Apple. It runs their tools; it does not speak for them.
Where it is now
Version 0.15.0. The workspace is built; shipping it properly is not finished.
- Built and in use
- Sessions, status detection, token and context usage, the session inspector, deep session search, git, files, artifacts, quick open and the command palette, GitHub, AI readiness, the dashboard, swarm view, split panes, accounts, hooks, the MCP inspector, the embedded browser and the agent that can drive it, the copilot and its routines, agents you add yourself, the settings window, and remote access from a paired phone, an iPhone, an Android phone or any browser.
- Not built yet
- Translations, notarisation on macOS, a Windows signing certificate, and voice dictation — the app cannot transcribe, so the microphone is off by default and hands over to the operating system's own dictation. Neither phone client is in an app store: the iPhone one is on TestFlight, internal testing only, and the Android one is a signed APK you download yourself.
- Platform
- macOS 12 or newer on Apple silicon, or Windows 10 or newer on x64. There is no Intel Mac build — macOS 27 does not run on Intel Macs — and no native ARM Windows build. The Windows one is produced natively in CI and the whole test suite runs on a Windows runner, so a red Windows test stops the release.
- Linux
- No window, and not nothing. The same core runs as a headless host — plain Node, no Electron in the process, no configuration file — which is what makes a Linux server or a WSL distribution a machine your phone and your desktop can open a session on. One line installs it, and it has been left running in a WSL distribution under a user service holding real agent sessions.
- Maturity
- Early. The macOS package is signed but not notarised and the Windows package is not signed, so macOS objects the first time you open it and Windows shows a SmartScreen panel. Use it on work that is under version control.