5815943861
Add Ctx Manager panel, setup wizard, import/export, session colors, ctx CLI flags (--shared, append, export), and FTS/WAL details. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
195 lines
9 KiB
Markdown
195 lines
9 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
## 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
|