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 cost.
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 what you have spent until the
bill arrives. 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; cost and context read from the transcripts the agent already writes; a chat view for when you want the conversation without the spinners; a browser next to it so the thing being built and the thing building it are one keystroke apart; and panels for git, files, search, GitHub, MCP, hooks and readiness, so that checking any of them is not a reason to leave the window.
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. Cost,
context, chat mode, 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, not even an update check — nothing imports the updater that sits in the dependency list. The only socket the app opens is a loopback endpoint for agent hooks to report to.
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 About screen's update button checks whether this build actually has an update feed and reports that it does not, rather than spinning and saying you are up to date. Profiles isolate Claude logins because that was verified against the real CLI; the other two agents are greyed out rather than given a plausible-looking switch that silently shares a login. A model with no published rate shows no cost instead of a guess. Chat mode is Claude Code only, and says so, because the transcript it reads is 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.1.2. The workspace is built; shipping it properly is not finished.
- Built and in use
- Sessions, status detection, cost and context, the session inspector, deep session search, git, files, quick open and the command palette, GitHub, AI readiness, the dashboard and board, swarm view, profiles, hooks, the MCP inspector, the embedded browser, and the settings window.
- Not built yet
- Session sharing between machines, translations, code signing and notarisation, and split panes — whose layout code is in the repository but is not wired to anything you can open. Apart from split panes, none of these is present in a half-finished form; they are simply not there. Updating in place is built, but only the macOS half has ever been run.
- 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 — no native ARM Windows build, and no Linux build at all. The Windows one is produced natively in CI, and it has now been installed and opened on Windows 11 x64, where 0.1.2 launches but cannot yet start a session.
- Maturity
- Early. Neither package is 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.