# 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](docs/v3-task_plan.md) for v3 architecture.

![BTerminal](screenshot.png)

## 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

```bash
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.).

```bash
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](https://github.com/DexterFromLab/BTerminal/releases) (built via CI on version tags).

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

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

## Usage

```bash
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.

```bash
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):

```markdown
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:

```bash
# 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](docs/multi-machine.md) for full architecture details.

## Telemetry (v2)

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

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

## License

MIT