~/ termdeck

One screen for every coding agent.

A local-first browser cockpit for running AI coding agents — Claude Code, Codex, Gemini — and plain shells side by side. Each window is a real shell on your machine; give every agent its own git worktree (a separate checkout on its own branch), get alerted when one needs approval, and reconnect without losing a session.

▶ Try the demo ★ View on GitHub Quick start

npx @kiril6/termdeck

Runs entirely on localhost. Your shells never leave your machine.
The demo is the real UI with no backend — click around, but shells won't run. Install to get live shells.

termdeck: three agents in separate git worktrees; one asks for approval, it is approved from the agent queue, its changes are reviewed and merged behind a passing test — Palette (⌘K) → New agent task → a git worktree per agent → red alert when one needs approval, amber when one is waiting → the agent queue jumps to it. Real UI; the agent CLIs are scripted stand-ins.

Works with what you already have

Claude Code Codex Gemini Copilot Cursor Agent OpenCode Qwen Code Antigravity Aider zsh bash PowerShell tmux durable sessions xterm.js GPU render Node ≥20 fully offline

For AI coding agents

Run several agents without losing track.

Claude Code, Codex and Gemini each in their own window and worktree — with a clear signal for which one needs you.

One-click agent CLIs

Claude Code, Codex, Gemini, Copilot, Cursor Agent, OpenCode, Qwen Code, Antigravity, Aider — or your own command — in a fresh shell from the palette. When the agent exits you drop back to the local shell, and after a reboot Claude, Codex, Gemini and Copilot tabs come back resumed.

A git worktree per agent

Each agent task is cut into its own worktree and opens as its own project tab — three agents working at once, zero overwriting. An orange dot warns when two of them touch the same file.

Know who needs you

A working agent pulses green on its tab and dock chip, a quiet one pulses amber; one blocked on an “Allow this tool?” prompt goes red — on the tab and its project, with the exact command and Approve / Deny buttons when hooks are on (nothing is answered without your click unless you opt in to a scoped rule — never for risky commands). Run termdeck hooks install to add the optional Claude Code, Codex, Copilot or Gemini CLI hooks and the state is exact, with the current tool and file; without them it falls back to output heuristics. termdeck never answers a prompt unless you click Approve / Deny, or opt in to a scoped rule.

One queue for the fleet

A single popover lists every agent tab across all projects, ranked needs approval → waiting → working. Click a row to jump to it — token totals per agent and project, as the agent reports them (Claude Code, Codex).

Review, then land it

Read-only diff of a worktree against the commit it was cut from — select a hunk and send it, with its file and line range, to an agent tab (typed, never run) — then merge it or open a PR and clean up the worktree, without leaving termdeck. Nothing is deleted without your confirm.

Private by default

Runs on your machine. No cloud, no telemetry, no API keys — your agents’ output never leaves localhost. Optional session logs for an audit trail.

Optional: exact agent state — wires up Claude Code, Codex, Copilot and Gemini CLI hooks. It shows what it will change and asks first; add --dry-run to only preview.

npx @kiril6/termdeck hooks install

Why termdeck

Why not just tmux, iTerm or a pile of tabs?

You get tmux's session persistence plus a point-and-click GUI you don't have to learn — floating windows, projects, and agent tooling in the browser you already have open, on macOS, Windows, and Linux alike.

tmux / iTerm / tabs

termdeck

Point-and-click GUI, nothing to learn

—

✓

Floating, draggable, tileable windows

partial

✓

Session survives disconnect / restart

✓

Projects, themes, command palette built in

✗

✓

A separate git worktree per agent task

—

✓

Alert when an agent needs approval, across projects

—

✓

Diff review of an agent’s worktree

—

✓

Same UI on macOS · Windows · Linux

varies

✓

Features

Everything, one screen.

Six things you'd normally wire together by hand — built in.

Floating windows

Drag, resize, tile into a grid, tabs per pane. Group windows into project tabs and switch context instantly.

Session reattach

Refresh the browser or drop your connection — the shell keeps running. A 60s grace timer holds the PTY and replays the buffer.

Durable with tmux

With tmux installed, shells survive a server restart or crash — not just a browser refresh.

Real filesystem tree

A live, resizable sidebar rooted at the active project. Turn on Follow and it reveals the focused terminal’s live folder. Open a shell in any folder; reveal files in Finder/Explorer.

Command palette

⌘K for fuzzy actions, sessions, and reusable snippets. Category chips (Terminals, Agents, Layout, Workspace…) narrow the list — Tab cycles them. Broadcast input to every shell in a project.

Themes & polish

Dracula, Nord, Gruvbox, Tokyo Night, Catppuccin and more. GPU rendering, font zoom, clickable links and file paths, pixel pets.

And a lot more

Built for how you actually work.

The rest of the toolbox.

Broadcast inputMirror keystrokes and snippets to every shell in a project.

Window glue (🔒)Snap adjacent windows and lock the pair to resize and move together.

SSH hostsSave targets, one-click connect; drop back to a local shell on disconnect.

Command snippetsReusable commands from the palette or each terminal's footer.

Run on startSpawn a shell that immediately runs npm run dev, ssh …, anything.

Live working directoryEach window's footer follows the shell as it cds and shows the last command and a globe icon for any detected dev-server port (click to open, right-click to copy the URL or stop it) — no shell config.

Send to agentSelect text in the file viewer, a diff or any terminal’s output and send it as a prompt to another terminal — no copy-paste.

Layout presetsToolbar Tile ▾ (or palette → Layout): auto-tile or a fixed 1×1, 2×1, 1×2, 2×2 or 3×2 grid; extra windows are minimized, not closed. ⌥1–9 jumps to the Nth window.

Live overviewToolbar Sessions → Grid: one read-only tile per session across every project, showing its latest output and whether it is running, waiting or needs approval. Most urgent first, with an All / Active filter to hide idle sessions. Click a tile to jump to it.

Phone alertsSet TD_NOTIFY_URL to an ntfy topic (or any webhook) and your phone buzzes when an agent needs approval; tapping it opens that terminal. Off unless you set it. Setup

Works on a phoneOn a narrow screen (e.g. over Tailscale) termdeck fits the screen: one full-size window at a time, switched from the dock, with a compact header and touch-sized buttons.

What's new & updatesHelp shows the version and the changelog offline, with a one-time note after an upgrade. Check for updates contacts npm only when you click it — no background requests.

Desktop right-click menuRight-click the empty desktop for a context-aware launcher: new terminal or agent task, open file, tile, restore, broadcast.

File viewerClick a file in the tree or use ⌘K → Open file; .md renders formatted, CSV becomes a table, and images, PDF, audio and video play in place. Reveal in Finder/Explorer, or open it in your editor (TD_EDITOR, default code).

Find & save outputSearch a terminal's history with match counts; download any terminal as a .log.

24 themes17 dark + 7 light, per-terminal or dashboard-wide, searchable.

Keyboard & screen readersEvery theme meets WCAG AA contrast for UI text. Move or resize a window with the keyboard (⌘K → Move or resize window), dialogs keep focus inside and give it back, and notifications are announced.

Mini-game while you waitDino or Snake, auto-armed on long runs, with a “still working…” nudge and a done-toast with duration.

Desktop notificationsCommand-done alerts when a shell you're not watching returns to its prompt.

Local-first & offlineLocal-only bind, a sign-in cookie per browser (termdeck open) so other programs on your machine can’t drive your shells, Origin/Host checks, a strict Content Security Policy, xterm served locally — no CDN.

Safe remote accessRandom access token whenever it’s reachable off-loopback; TD_ALLOWED_HOSTS for tailscale serve. Setup guide

Session logsSet TD_LOG_DIR and each shell’s output is saved when it exits — an audit trail for long agent runs.

Named layouts⌘K → Save layout as… names your whole workspace — projects, windows, tabs and folders — and Restore layout… brings it back in new shells. Stored locally in ~/.termdeck/; agents are never relaunched.

Export / import settings⌘K → Export settings… saves your theme, font, snippets, SSH hosts and AI CLI presets to one file; Import settings… loads it in another browser.

AutostartOne command, termdeck autostart install, sets up a launchd agent or systemd user unit — preview with --dry-run. Needs a global install (npm i -g) or a clone. Details

Install as an appChrome or Edge: click the install icon. Safari: File → Add to Dock. termdeck gets its own window with no tabs or address bar. It is a window onto the running server, on one fixed address, so pin an uncommon port (17300; dev servers often take 3000): after npm i -g @kiril6/termdeck, termdeck autostart install --port 17300 runs it now and at every login (macOS, Linux).

Doctortermdeck doctor checks Node, node-pty, tmux, git and the port — offline, with the fix next to each problem.

Clean uninstalltermdeck uninstall removes agent hooks, start-at-login, termdeck’s tmux sessions and ~/.termdeck in one step, after showing what it will do (--dry-run to preview).

Clickable file pathsPaths in output (src/a.ts:42) open in the viewer at that line.

See the full feature list → What's new

Shipping steadily.

The latest releases, straight from GitHub.

All releases → Get started

Quick start

Requires Node.js 20+. No build step, no Electron.

Fetch and run in one command — no clone needed

npx @kiril6/termdeck

Keep it installed — puts termdeck on your PATH for daily use; npx above runs once and leaves nothing behind

npm i -g @kiril6/termdeck

Or clone it — setup picks the right node-pty prebuilt for your OS, then serves on port 3000

node install.js && npm start

Optional: install tmux first — shells then survive a server restart, not just a browser refresh

brew install tmux

Optional: exact agent state — hooks for Claude Code, Codex, Copilot and Gemini CLI; shows what it changes and asks first (--dry-run to preview)

npx @kiril6/termdeck hooks install

Optional: install it as a desktop app — after step 2, run the command below: it starts termdeck now and at every login on a fixed, uncommon port (dev servers often take 3000). Then run termdeck open and click the install icon in Chrome or Edge (Safari: File → Add to Dock). On Windows, where autostart isn’t available: termdeck --port 17300

termdeck autostart install --port 17300

This is a local-first tool, not a static site. Its core is a Node process that spawns real PTYs — so it runs on your machine, not on GitHub Pages. This page is just the showcase; grab the code and run it locally.