@jhizzard/termdeck 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Izzard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# TermDeck
+
+![TermDeck running 6 terminals in a 3x2 control room layout](assets/hero.jpg)
+
+Web-based terminal multiplexer with AI-aware session management, rich metadata overlays, and cross-project RAG integration.
+
+Think of it as tmux in your browser — but each terminal panel shows you what project it belongs to, what the AI is doing, and pipes everything into your memory system.
+
+![30 second demo](assets/demo.gif)
+
+## Install
+
+```bash
+npx @jhizzard/termdeck
+```
+
+That's it — the published package ships prebuilt binaries for `node-pty` and `better-sqlite3`, so you don't need a C++ toolchain for the common path (Node 20/22/24 on macOS, Linux, Windows).
+
+### From source
+
+```bash
+git clone https://github.com/jhizzard/termdeck.git
+cd termdeck
+npm install
+npm run dev
+```
+
+### Prerequisites for source builds only
+
+If prebuilt binaries are unavailable for your platform (rare), TermDeck falls back to compiling [node-pty](https://github.com/microsoft/node-pty) locally. In that case you'll need:
+
+- **macOS**: `xcode-select --install` (installs Xcode Command Line Tools)
+- **Windows**: Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the "Desktop development with C++" workload
+- **Linux (Debian/Ubuntu)**: `sudo apt install build-essential python3`
+- **Linux (Fedora)**: `sudo dnf groupinstall "Development Tools"`
+
+If `npm install` fails with errors mentioning `node-gyp`, `gyp`, or `node-pty`, you're missing the compiler.
+
+### macOS
+```bash
+npm run install:app
+# Creates ~/Applications/TermDeck.app — double-click to launch, drag to Dock
+```
+
+### Windows
+```cmd
+install.bat
+# Creates Start Menu + Desktop shortcuts
+```
+
+### Linux
+```bash
+npm run dev
+# Or: node packages/cli/src/index.js
+```
+
+No terminal needed after installation — TermDeck opens your browser automatically.
+
+## What it does
+
+TermDeck gives you a single browser window with multiple embedded terminal panels. Each panel is a real PTY — full ANSI/VT100 support, so Claude Code, Gemini CLI, vim, htop, and any other terminal app works exactly as it would in a native terminal.
+
+Each terminal panel has:
+
+- **Status indicator** — green (active), purple (thinking), amber (idle), red (errored)
+- **Type detection** — automatically identifies Claude Code, Gemini CLI, Python servers, or plain shells
+- **Project tag** — color-coded project association
+- **Metadata strip** — when opened, why, last commands, detected ports, request counts
+- **Individual controls** — theme selector, focus/half/close, AI question input
+- **Per-terminal theming** — Tokyo Night, Rose Pine Dawn, Catppuccin, Dracula, Nord, and more
+
+## Layout modes
+
+Designed for iMac-scale screens. Layout modes let you see the right amount of detail:
+
+| Mode | Grid | Use case |
+|------|------|----------|
+| 1x1 | Single terminal | Deep work with one AI agent |
+| 2x1 | Two columns | Half-screen split |
+| 2x2 | 2x2 grid | Four terminals at comfortable size |
+| 3x2 | 3x2 grid | Six terminals, monitoring mode |
+| 2x4 | 2x4 grid | Eight terminals, tall vertical pairs |
+| 4x2 | 4x2 grid | Eight terminals, control room |
+| Focus | One expanded | Temporarily expand any panel |
+| Half | One large + stack | One primary + secondary panels |
+
+## Prompt bar
+
+The bottom prompt bar launches new terminals:
+
+```
+> bash                              # Plain shell
+> claude code ~/my-project          # Claude Code in a directory
+> python3 manage.py runserver       # Django dev server
+> cc my-project                     # Shorthand: Claude Code + project
+> gemini                            # Gemini CLI
+> npx vitest run                    # One-shot command
+```
+
+Select a project from the dropdown to auto-tag and auto-`cd` into the project directory.
+
+## Configuration
+
+The installer creates `~/.termdeck/config.yaml`. Edit it to define your projects:
+
+```yaml
+port: 3000
+shell: /bin/zsh
+defaultTheme: tokyo-night
+
+projects:
+  my-project:
+    path: ~/code/my-project
+    defaultTheme: catppuccin-mocha
+    defaultCommand: claude
+
+rag:
+  enabled: false
+  supabaseUrl: https://your-project.supabase.co
+  supabaseKey: your-anon-key
+```
+
+## RAG integration
+
+TermDeck has a three-layer memory system:
+
+1. **Session memory** — what happened in each terminal session
+2. **Project memory** — commands, file edits, and patterns shared across sessions within a project
+3. **Developer memory** — cross-project patterns (your habits, common workflows, error resolutions)
+
+Events are always recorded to local SQLite (`~/.termdeck/termdeck.db`). Enable Supabase sync by adding your credentials to the config file and running `config/supabase-migration.sql` in your Supabase SQL editor.
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| Ctrl+Shift+N | Focus prompt bar |
+| Ctrl+Shift+1 | Layout: 1x1 |
+| Ctrl+Shift+2 | Layout: 2x1 |
+| Ctrl+Shift+3 | Layout: 2x2 |
+| Ctrl+Shift+4 | Layout: 3x2 |
+| Ctrl+Shift+5 | Layout: 2x4 |
+| Ctrl+Shift+6 | Layout: 4x2 |
+| Ctrl+Shift+] | Next terminal |
+| Ctrl+Shift+[ | Previous terminal |
+| Escape | Exit focus/half mode |
+
+## Architecture
+
+```
+Browser (xterm.js panels)
+    | WebSocket (1 per terminal)
+Node.js server
+    |-- Session manager (create, destroy, metadata)
+    |-- WebSocket hub (mux terminal I/O)
+    |-- REST API (CRUD, resize, themes)
+    |-- Output analyzer (status detection)
+    |-- RAG event recorder (SQLite + Supabase sync)
+        | node-pty
+OS pseudo-terminals
+    |-- bash/zsh
+    |-- Claude Code
+    |-- python3 servers
+    |-- Gemini CLI
+    |-- any CLI tool
+        |
+SQLite (local) --sync--> Supabase (RAG)
+```
+
+## Security
+
+TermDeck gives each terminal panel full shell access on your machine. It binds to `127.0.0.1` (localhost only) by default.
+
+**Do NOT expose TermDeck to the network without authentication.** There is no built-in auth in v0.1. If you need remote access, put it behind a VPN or SSH tunnel.
+
+## Tech stack
+
+- **Server**: Node.js, Express, node-pty, ws, better-sqlite3
+- **Client**: xterm.js, xterm-addon-fit, vanilla JS (no build step)
+- **Storage**: SQLite (local), Supabase/PostgreSQL (RAG)
+- **Themes**: 8 curated terminal color schemes
+- **Launch**: macOS .app bundle (no terminal needed)
+
+## How to test
+
+After installing, verify each feature works:
+
+1. **Launch** — Double-click TermDeck.app or run `npm run dev`. Browser should open automatically.
+2. **Create terminals** — Type `bash` in the prompt bar and click Launch. Verify the terminal is interactive (`ls`, `pwd`, `echo hello`).
+3. **Multiple terminals** — Open 4+ terminals. Verify they're independent.
+4. **Layouts** — Click each layout button (1x1 through 4x2). Try Ctrl+Shift+1-6.
+5. **Focus/Half** — Click the focus (square) and half (rectangle) buttons on a panel. Press Escape to exit.
+6. **Keyboard nav** — Use Ctrl+Shift+] and [ to cycle between terminals.
+7. **Metadata** — Run commands and verify "last command" updates in the metadata strip.
+8. **Port detection** — Run `python3 -m http.server 8888`. Verify port shows in metadata and type changes to "Python Server".
+9. **Themes** — Change themes on two terminals independently via the dropdown.
+10. **Projects** — Select a project from the dropdown, launch a terminal. Verify it cd's to the right directory.
+11. **Terminal exit** — Type `exit` in a terminal. Panel should dim with "Exited (0)".
+12. **Persistence** — Restart the server. Old sessions should be marked as exited in the DB.
+13. **Command history** — Check `GET http://localhost:3000/api/sessions/:id/history`.
+14. **RAG events** — Check `GET http://localhost:3000/api/rag/events` to see recorded events.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run server directly
+npm run server
+
+# Run via CLI (opens browser)
+npm run dev
+
+# The client is served as static files from packages/client/public/
+```
+
+## Troubleshooting
+
+### `npm install` fails with node-gyp errors
+
+Install the C++ compiler for your platform (see Prerequisites above), then:
+
+```bash
+npm cache clean --force
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Terminal panels don't respond to input
+
+Check that node-pty compiled correctly:
+
+```bash
+node -e "require('node-pty')"
+```
+
+If this throws an error, reinstall with: `npm rebuild node-pty`
+
+## License
+
+MIT

package/config/config.example.yaml

@@ -0,0 +1,58 @@
+# TermDeck Configuration
+# Copy to ~/.termdeck/config.yaml and customize
+
+port: 3000
+host: 127.0.0.1
+shell: /bin/zsh    # or /bin/bash
+
+defaultTheme: tokyo-night
+
+# Project definitions
+# Each project maps a name to a directory + defaults
+# These appear in the prompt bar dropdown and enable auto-cd + default themes
+projects:
+  # my-project:
+  #   path: ~/code/my-project
+  #   defaultTheme: catppuccin-mocha
+  #   defaultCommand: claude         # or bash, gemini, etc.
+  # another-project:
+  #   path: ~/code/another-project
+  #   defaultTheme: dracula
+  #   defaultCommand: bash
+
+# RAG Integration (Supabase)
+# Multi-layer memory: session -> project -> developer
+# Events are always recorded to local SQLite.
+#
+# Secrets live in ~/.termdeck/secrets.env (see config/secrets.env.example).
+# Values below use ${VAR} substitution so this file stays free of secrets.
+rag:
+  enabled: false
+  supabaseUrl: ${SUPABASE_URL}
+  supabaseKey: ${SUPABASE_SERVICE_ROLE_KEY}
+  openaiApiKey: ${OPENAI_API_KEY}
+  anthropicApiKey: ${ANTHROPIC_API_KEY}
+  # developerId: your-username (defaults to OS username)
+  syncIntervalMs: 10000
+
+  # Engram bridge — how /api/ai/query talks to @jhizzard/engram.
+  #   direct  — server embeds + queries Supabase itself (default, preserves v0.1 behavior)
+  #   webhook — POST to a running `engram serve` HTTP webhook (see engramWebhookUrl)
+  #   mcp     — spawn the local `engram` binary and talk JSON-RPC over stdio
+  engramMode: direct
+  engramWebhookUrl: http://localhost:37778/engram
+  # engramBinary: engram   # override path to the @jhizzard/engram CLI for mcp mode
+
+  # Supabase table names (created by config/supabase-migration.sql)
+  tables:
+    session: engram_session_memory
+    project: engram_project_memory
+    developer: engram_developer_memory
+    commands: engram_commands
+
+# Per-session markdown logs written to ~/.termdeck/sessions/ on session exit.
+# Zero-config: works without Supabase / OpenAI. Optional LLM summary requires
+# ANTHROPIC_API_KEY (env or rag.anthropicApiKey). CLI flag: `termdeck --session-logs`.
+sessionLogs:
+  enabled: false
+  summaryModel: claude-haiku-4-5

package/config/secrets.env.example

@@ -0,0 +1,17 @@
+# TermDeck secrets (F2.2)
+# Copy this file to ~/.termdeck/secrets.env and fill in the values.
+# ~/.termdeck/secrets.env should NEVER be committed — it lives outside the repo.
+#
+# These keys are referenced from ~/.termdeck/config.yaml via ${VAR} substitution,
+# so you can edit yaml freely without accidentally leaking a secret.
+
+# Supabase project that backs the RAG / Engram memory tables.
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=
+
+# OpenAI embeddings — only needed when rag.engramMode is `direct`.
+OPENAI_API_KEY=
+
+# Anthropic — powers the session-log summarizer (T2.5) and any future
+# LLM-backed features that run server-side.
+ANTHROPIC_API_KEY=

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@jhizzard/termdeck",
+  "version": "0.2.0",
+  "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
+  "bin": {
+    "termdeck": "./packages/cli/src/index.js"
+  },
+  "main": "packages/cli/src/index.js",
+  "files": [
+    "packages/cli/src/**",
+    "packages/server/src/**",
+    "packages/client/public/**",
+    "config/config.example.yaml",
+    "config/secrets.env.example",
+    "LICENSE",
+    "README.md"
+  ],
+  "workspaces": [
+    "packages/server",
+    "packages/client",
+    "packages/cli"
+  ],
+  "scripts": {
+    "dev": "node packages/server/src/index.js",
+    "server": "node packages/server/src/index.js",
+    "start": "NODE_ENV=production node packages/cli/src/index.js",
+    "install:app": "bash install.sh"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "ws": "^8.16.0",
+    "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
+    "better-sqlite3": "^12.9.0",
+    "uuid": "^9.0.0",
+    "yaml": "^2.3.4",
+    "chalk": "^5.3.0",
+    "open": "^10.0.0"
+  },
+  "keywords": [
+    "terminal",
+    "multiplexer",
+    "xterm",
+    "pty",
+    "web-terminal",
+    "tmux-alternative",
+    "claude-code",
+    "memory",
+    "flashback",
+    "rag",
+    "devtools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhizzard/termdeck.git"
+  },
+  "homepage": "https://github.com/jhizzard/termdeck#readme",
+  "bugs": {
+    "url": "https://github.com/jhizzard/termdeck/issues"
+  },
+  "author": "Joshua Izzard",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/cli/src/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+// TermDeck CLI launcher
+// Usage: termdeck [--port 3000] [--no-open]
+
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Parse CLI args
+const args = process.argv.slice(2);
+const flags = {};
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--port' && args[i + 1]) {
+    flags.port = parseInt(args[i + 1], 10);
+    i++;
+  } else if (args[i] === '--no-open') {
+    flags.noOpen = true;
+  } else if (args[i] === '--session-logs') {
+    flags.sessionLogs = true;
+  } else if (args[i] === '--help' || args[i] === '-h') {
+    console.log(`
+  TermDeck - Web-based terminal multiplexer
+
+  Usage:
+    termdeck                    Start with defaults (port 3000)
+    termdeck --port 8080        Start on custom port
+    termdeck --no-open          Don't auto-open browser
+    termdeck --session-logs     Write per-session markdown logs to ~/.termdeck/sessions/
+
+  Keyboard shortcuts (in browser):
+    Ctrl+Shift+N                Focus prompt bar
+    Ctrl+Shift+1-6              Switch layout (1x1 → 4x2)
+    Ctrl+Shift+] / [            Next / previous terminal
+    Escape                      Exit focus/half mode
+
+  Config:
+    ~/.termdeck/config.yaml     Server + project + RAG configuration
+    ~/.termdeck/termdeck.db     Session history (SQLite)
+`);
+    process.exit(0);
+  }
+}
+
+// Load and start server
+const { createServer, loadConfig } = require(path.join(__dirname, '..', '..', 'server', 'src', 'index.js'));
+
+// Flag-driven env vars must be set BEFORE loadConfig() so any module that
+// reads process.env at require-time sees them.
+if (flags.sessionLogs) {
+  process.env.TERMDECK_SESSION_LOGS = '1';
+}
+
+const config = loadConfig();
+if (flags.port) config.port = flags.port;
+if (flags.sessionLogs) {
+  config.sessionLogs = { ...(config.sessionLogs || {}), enabled: true };
+  console.log('[cli] session logs enabled — writing to ~/.termdeck/sessions/ on panel exit');
+}
+
+const { server } = createServer(config);
+const port = config.port || 3000;
+const host = config.host || '127.0.0.1';
+const url = `http://${host}:${port}`;
+
+server.listen(port, host, async () => {
+  console.log(`
+  ╔══════════════════════════════════════╗
+  ║            TermDeck v0.2.0           ║
+  ╠══════════════════════════════════════╣
+  ║  ${url.padEnd(34)}  ║
+  ║                                      ║
+  ║  Ctrl+C to stop                      ║
+  ╚══════════════════════════════════════╝
+  `);
+
+  // Skip auto-open in Codespaces/CI (port forwarding handles it)
+  const isCodespaces = !!process.env.CODESPACES || !!process.env.GITHUB_CODESPACE_TOKEN;
+  const isCI = !!process.env.CI;
+
+  if (!flags.noOpen && !isCodespaces && !isCI) {
+    try {
+      const { platform } = require('os');
+      const cmd = platform() === 'darwin' ? 'open'
+        : platform() === 'win32' ? 'start'
+        : 'xdg-open';
+      execSync(`${cmd} ${url}`, { stdio: 'ignore' });
+    } catch (err) {
+      console.error('[cli] auto-open browser failed:', err.message);
+      console.log(`  Open ${url} in your browser\n`);
+    }
+  } else if (isCodespaces) {
+    console.log(`  Codespaces detected — use the Ports tab to open the browser\n`);
+  }
+});
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n  Shutting down TermDeck...');
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 3000);
+});