BTerminal

GTK 3 terminal with SSH & Claude Code session management, macros, and a cross-session context database. Catppuccin Mocha theme.

v2 complete, v3 all phases complete. v2: Multi-session Claude agent dashboard using Tauri 2.x + Svelte 5. v3: Multi-project mission control dashboard (All Phases 1-10 complete + sidebar redesign) -- project groups with per-project Claude sessions, session continuity (persist/restore agent messages), team agents panel, terminal tabs, VSCode-style left sidebar (vertical icon rail + expandable drawer panel + always-visible workspace), command palette with group switching. Features: project groups (up to 5 projects per group, horizontal layout, adaptive viewport count), per-project Claude sessions with session continuity, team agents panel (compact subagent cards), terminal tabs (shell/SSH/agent per project), agent panes with structured output, tree visualization with subtree cost and session resume, subagent/agent-teams support, multi-machine support (bterminal-relay WebSocket server + RemoteManager), Claude profile/account switching (switcher-claude integration), skill discovery and autocomplete (type / in agent prompt), SSH session management, ctx context database viewer, SQLite session persistence with layout restore, live markdown file viewer with Shiki syntax highlighting, 17 themes in 3 groups (4 Catppuccin + 7 Editor + 6 Deep Dark: Tokyo Night, Gruvbox Dark, Ayu Dark, Poimandres, Vesper, Midnight), global font controls (separate UI font [sans-serif] + terminal font [monospace] with live preview), .deb + AppImage packaging, GitHub Actions CI, 138 vitest + 36 cargo tests. Branch v2-mission-control. See docs/v3-task_plan.md for v3 architecture.

Features

• SSH sessions — saved configs (host, port, user, key, folder, color), one-click connect from sidebar
• Claude Code sessions — saved configs with sudo askpass, resume, skip-permissions and initial prompt
• SSH macros — multi-step automation (text, key press, delay) bound to sessions, runnable from sidebar
• Tabs — multiple terminals in tabs with reordering, auto-close and shell respawn
• Folder grouping — organize both SSH and Claude Code sessions in collapsible sidebar folders
• Session colors — 10 Catppuccin accent colors for quick visual identification
• Sudo askpass — temporary helper for Claude Code sudo mode: password entered once, auto-cleanup on exit
• Catppuccin Mocha — full theme across terminal, sidebar, tabs, dialogs and scrollbars

Context Manager

• ctx CLI — SQLite-based tool for persistent context across Claude Code sessions
• Ctx Manager panel — sidebar tab for browsing, editing and managing all project contexts
• Ctx Setup Wizard — step-by-step project setup with auto-detection from README and CLAUDE.md generation
• Import / Export — selective import and export of projects, entries, summaries and shared context via JSON with checkbox tree UI

Installation

git clone https://github.com/DexterFromLab/BTerminal.git
cd BTerminal
./install.sh

The installer will:

1. Install system dependencies (python3-gi, GTK3, VTE)
2. Copy files to ~/.local/share/bterminal/
3. Create symlinks: bterminal and ctx in ~/.local/bin/
4. Initialize context database at ~/.claude-context/context.db
5. Add desktop entry and icon to application menu

v2 Installation (Tauri — build from source)

Requires Node.js 20+, Rust 1.77+, and system libraries (WebKit2GTK 4.1, GTK3, etc.).

git clone https://github.com/DexterFromLab/BTerminal.git
cd BTerminal
./install-v2.sh

The installer checks all dependencies, offers to install missing system packages via apt, builds the Tauri app, and installs the binary as bterminal-v2 in ~/.local/bin/.

Pre-built .deb and AppImage packages are available from GitHub Releases (built via CI on version tags).

v1 Manual dependency install (Debian/Ubuntu/Pop!_OS)

sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-vte-2.91

Usage

bterminal

Context Manager (ctx)

ctx is a SQLite-based tool for managing persistent context across Claude Code sessions. It uses FTS5 full-text search and WAL journal mode.

ctx init myproject "Project description" /path/to/project
ctx get myproject                    # Load project context
ctx get myproject --shared           # Include shared context
ctx set myproject key "value"        # Save a context entry
ctx append myproject key "more"      # Append to existing entry
ctx shared set preferences "value"   # Save shared context (all projects)
ctx summary myproject "What was done" # Save session summary
ctx search "query"                   # Full-text search across everything
ctx list                             # List all projects
ctx history myproject                # Show session history
ctx export                           # Export all data as JSON
ctx delete myproject [key]           # Delete project or entry
ctx --help                           # All commands

Ctx Manager Panel

The sidebar Ctx tab provides a GUI for the context database:

• Browse all projects and their entries in a tree view
• View entry values and project details in the detail pane
• Add, edit and delete projects and entries
• Export — select specific projects, entries, summaries and shared context to save as JSON
• Import — load a JSON file, preview contents with checkboxes, optionally overwrite existing entries

Integration with Claude Code

Add a CLAUDE.md to your project root (the Ctx Setup Wizard can generate this automatically):

On session start, load context:
  ctx get myproject

Save important discoveries: ctx set myproject <key> <value>
Before ending session: ctx summary myproject "<what was done>"

Claude Code reads CLAUDE.md automatically and will maintain the context database.

Configuration

Config files in ~/.config/bterminal/:

File	Description
sessions.json	SSH sessions and macros
claude_sessions.json	Claude Code session configs

Context database: ~/.claude-context/context.db

Keyboard Shortcuts

Shortcut	Action
Ctrl+T	New tab (local shell)
Ctrl+Shift+W	Close tab
Ctrl+Shift+C	Copy
Ctrl+Shift+V	Paste
Ctrl+PageUp/Down	Previous/next tab

Multi-Machine Support (v2)

BTerminal v2 can manage agents and terminals running on remote machines via the bterminal-relay binary.

Architecture

BTerminal (Controller) --WebSocket--> bterminal-relay (Remote Machine)
                                      ├── PtyManager (remote terminals)
                                      └── SidecarManager (remote agents)

Running the Relay

On each remote machine:

# Build the relay binary
cd v2 && cargo build --release -p bterminal-relay

# Start with token auth
./target/release/bterminal-relay --port 9750 --token <secret>

# Dev mode (allow unencrypted ws://)
./target/release/bterminal-relay --port 9750 --token <secret> --insecure

Add remote machines in BTerminal Settings > Remote Machines (label, URL, token). Remote panes auto-group by machine label in the sidebar. Connections automatically reconnect with exponential backoff (1s-30s cap) on disconnect.

See docs/multi-machine.md for full architecture details.

Telemetry (v2)

BTerminal supports OpenTelemetry tracing with optional export to Tempo + Grafana.

# Start the tracing stack
cd docker/tempo && docker compose up -d
# Grafana at http://localhost:9715

# Run BTerminal with OTLP export enabled
BTERMINAL_OTLP_ENDPOINT=http://localhost:4318 npm run tauri dev

Without BTERMINAL_OTLP_ENDPOINT, telemetry falls back to console-only tracing (no network calls). Key Tauri commands (PTY, agent, remote) are instrumented with #[tracing::instrument]. Frontend events (agent lifecycle, errors, cost) route to Rust tracing via IPC bridge.

Documentation

Document	Description
docs/task_plan.md	v2 architecture decisions, error handling, testing strategy
docs/phases.md	v2 implementation phases (1-7 + multi-machine A-D) with checklists
docs/findings.md	Research findings (Agent SDK, Tauri, xterm.js, performance)
docs/progress.md	Session-by-session progress log (recent)
docs/progress-archive.md	Archived progress log (2026-03-05 to 2026-03-06 early)
docs/multi-machine.md	Multi-machine architecture (implemented, WebSocket relay, reconnection)
docs/v3-task_plan.md	v3 Mission Control redesign: architecture decisions and strategies
docs/v3-findings.md	v3 research findings and codebase reuse analysis
docs/v3-progress.md	v3 session progress log (All Phases 1-10 complete)

License

MIT