ByteDesk Terminal

Native Linux mission cockpit for building ByteDesk with VTE-backed terminals.

What this is

ByteDesk Terminal is a GTK4/libadwaita desktop app that corrals terminal-first work into missions. A mission owns:

• the BDP/Jira context
• the platform repo or worktree path
• tmux-backed VTE terminal sessions
• captured ADHD thoughts
• event-only timeline history
• Git, GitHub, Jira, and OpenClaw integration surfaces

The terminal renderer is native VTE. Managed sessions are backed by tmux so Codex, Claude, shells, tests, logs, and OpenClaw sessions can survive an app restart.

Native dependencies

Ubuntu/Noble packages needed for the full native UI build:

sudo apt-get install -y \
  libgtk-4-dev \
  libadwaita-1-dev \
  libvte-2.91-gtk4-dev \
  libgraphene-1.0-dev

Runtime CLIs expected by the cockpit:

git gh tmux openclaw codex claude

The app stores local state in the platform-specific user data directory via SQLite. It does not persist full terminal transcripts by default.

Development

Core tests, usable even before native GTK development packages are installed:

cargo test --no-default-features

Full native build and run:

cargo run

The default Cargo feature is native-ui, which pulls in GTK4, libadwaita, and VTE. Use --no-default-features only for core storage/model/integration tests.

Fast iteration / hot-reload during UI work

CSS / styling (real-time, no restart):

• In normal cargo run (debug) builds, src/style.css is watched automatically.
• Edit src/style.css, save → the running window restyles instantly.
• You will see 🎨 Live CSS hot-reload enabled and 🎨 CSS hot-reloaded in the terminal that launched the app.
• You can force it even for release builds with BDTERM_LIVE_CSS=1 cargo run.

Rust code changes (widget logic, new panes, etc.):

Install once:

cargo install cargo-watch

Then use the dev runner (it auto-kills the previous instance so you don't get stale windows stacking up):

./scripts/dev-run.sh

Or the manual equivalent:

pkill -f 'target/debug/bytedesk-terminal' || true
cargo watch -x 'run --features native-ui'

Small Rust edits usually rebuild + restart the window in < 2 seconds. The new instance comes up focused with your latest changes.

Current slice (v1)

See docs/DESIGN.md for the full architecture, layout, density rules, keymap, capability set, and pattern map.

Implemented:

• AgentRegistry + Adapter trait (subsystem A) with built-ins: shell, claude, codex, grok, tests, logs. Adding a new agent is one file plus one register() line.
• EventBus typed pub-sub (subsystem I) with feature-gated pump (glib MainContext under native-ui, std::thread under no-default-features)
• Telemetry sink trait + NoopSink (subsystem L Wire Tap)
• Per-aggregate Repositories over SQLite (subsystem H): Mission / Thought / TerminalSession / Timeline / PromptVault / Context / PaneTree
• TmuxSupervisor over TmuxBackend trait + CliTmux + FakeTmux (subsystem J)
• PaneState enum + PaneTree Composite (subsystems B + C)
• LayoutSnapshot persistence (subsystem H, JSON blob round-trip)
• Cockpit shell — Layout C dense, dark-only: 5-zone scaffold + header + status bar + missions rail + agents rail + dock (7 tabs) + Raycast palette + mission create/import dialog
• Workspace: tabbed VTE panes per agent, restore on launch from persisted TerminalSessions, ⌘T / ⌘W / ⌘1..9 keymap
• Memory sync (subsystem F): one source → 5 dialects (CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md)
• Smart paste classifier chain (subsystem E): stack-trace, diff, URL, JSON, plain fallback
• ScatterGather + Aggregator + Verdict state machine (subsystem D)
• Voice push-to-talk backend: whisper.cpp detection + WAV capture trait
• Context bus (per-mission scratchpad file + DB log)
• Prompt vault (templated prompts with {{var}} substitution)
• Responsive collapse rules + prefers-reduced-motion respect
• Typed errors per subsystem (thiserror) — anyhow only at binary edges
• AppCtx aggregate (constructor injection, no DI container)

Test status:

• cargo test --no-default-features: 100 passing
• cargo test: 98 passing (2 EventBus tests skip native-ui due to MainContext)
• cargo check (native-ui): clean

Deferred to v1.1 (intentional):

• Recursive split panes (one VTE per tab in v1)
• Smart-collapse agents rail on agent activity
• Diff review surface
• Approval queue for agent tool-call requests
• Cost & token telemetry chips
• Floating pane detach
• Desktop notifications on agent finish
• Real audio capture (currently silent-WAV stub for whisper pipeline)
• ⌘⇧R race UI (model exists in flow/, GTK wiring pending)
• Light theme