A browser-based terminal workspace for developers who juggle multiple projects. Split panes, project switching, file browsing — no IDE overhead. Especially useful for CLI-based agentic coding workflows where each project needs 3-4 terminals running simultaneously.
- Multi-project workspace — organize terminals by project, switch between them instantly
- Unlimited split panes — side-by-side terminals with draggable dividers per tab
- Live sidebar cockpit — per-project status (active/idle/dead), terminal count, elapsed time
- Per-project file browsing — browse any project's files and open them in your editor
- Truthful terminal scrollback — VS Code-style scrolling, snapshot-first reconnects, and visible warnings when preserved history cannot be guaranteed
- Terminal resilience — debug inspector, transport replay catch-up, visibility-aware recovery, heartbeat monitoring
- Durable sessions — tmux-backed sessions survive browser detaches and server restarts
- Toast notifications — success/error feedback on every action, no silent failures
Prerequisites: Node.js 22+, npm 10+, and tmux (required for terminal sessions).
# Install dependencies
npm install
# Start both servers (backend :43001, frontend :43000)
./server.sh start
# Manage the service
./server.sh stop # Stop gracefully
./server.sh restart # Restart
./server.sh status # Check status
./server.sh logs # Show recent logsOpen http://localhost:43000 in your browser.
- Click + in the sidebar to add a project (give it a name and the absolute path).
- Click a project to open a terminal scoped to that directory.
- Use Split right (columns icon) to add side-by-side terminal panes — drag dividers to resize, double-click to reset.
- Use + in the tab bar to open new terminal tabs. Each tab has its own set of panes.
- The sidebar shows live status per project: terminal count, activity indicator (green = active, gray = idle, red = dead), and elapsed time.
- Click the folder icon on any project row to browse its files — clicking a file opens it in your configured editor.
- Toast notifications confirm every action and surface errors.
CodeDeck includes built-in resilience features for debugging and recovering misbehaving panes:
- Debug inspector — click the bug icon on any pane to see health status, lifecycle timeline, and diagnostics
- Recovery actions — Reconnect, Resync (transport catch-up without teardown), and Redraw (force repaint)
- Truthful reconnects — every attach/reconnect clears stale browser history and reseeds from a fresh tmux snapshot of the recent 10,000-line window
- Visibility-aware recovery — returning to a backgrounded tab automatically resizes, resyncs, and catches up missed live output
- Replay buffer — bounded per-session output buffer is transport-only catch-up, not the preserved-history authority
- Heartbeat & stall detection — detects stale views (throttled, paint lag) and surfaces the reason
CodeDeck requires tmux for all terminal sessions. If tmux is missing, the UI blocks terminal creation and prompts you to install it instead of silently downgrading durability.
# Supported terminal runtime contract
CODEDECK_TERMINAL_RUNTIME=tmux ./server.sh startLegacy non-tmux runtime values are ignored; the backend still enforces tmux-required terminals.
Set CODEDECK_CAFFEINATE=1 to wrap the server under caffeinate -i, preventing idle sleep.
Projects and settings are stored in SQLite at ~/.codedeck.db:
defaultPath— starting directory for the project pickereditorCommand— command for opening files (defaults tocode -r)
Browser (React + xterm.js)
↕ WebSocket (terminal I/O)
↕ REST (projects, files, sessions, health)
Node.js server (Express + node-pty)
↕ PTY pool (one per terminal pane)
↕ SQLite (project config)
↕ fs (file tree reads)
↕ child_process (open files in editor)
See docs/steering/ for detailed architecture, tech stack, and project structure.
See CONTRIBUTING.md for development setup and guidelines.