README.md
signaltty — native Linux workspace for parallel AI coding agents
A terminal multiplexer designed for agent-driven development: a persistent session server owns PTYs and state; a CLI and a native GTK4/libadwaita GUI attach as pure clients. Closing the UI never kills running agents.
Status: Phase 4 (extensibility) implemented and tested. All MVP phases (multiplexer core, agent awareness, native GUI, executable plugins) are done.
Quick start
| 1 | cargo build --release |
| 2 | ./target/debug/signaltty daemon # start the session server |
| 3 | ./target/debug/signaltty integration install all # hook shims (codex/claude/opencode/cursor) |
| 4 | ./target/debug/signaltty new --cwd ~/code/project -- codex |
| 5 | ./target/debug/signaltty new --cwd ~/code/project -- claude |
| 6 | ./target/debug/signaltty pane read <pane-id> |
| 7 | ./target/debug/signaltty pane attach <pane-id> # Ctrl+] to detach |
| 8 | ./target/debug/signaltty wait --pane <id> --until done |
| 9 | ./target/debug/signaltty pane resume <pane-id> # after restart, via native resume |
Note: codex trusts new hooks interactively ("Trust all and continue"
once per hook command); codex exec needs
--dangerously-bypass-hook-trust to fire untrusted hooks.
Global flags: --socket <path> (default
$XDG_RUNTIME_DIR/signaltty/signaltty.sock), --json (machine-readable
result object; resource-creating commands return opaque ids).
Architecture
| 1 | signaltty-server ── owns PTYs, processes, workspaces, scrollback, |
| 2 | lifecycle, attention, persistence, IPC |
| 3 | signaltty ───────── CLI client (same API as the GUI) |
| 4 | signaltty-gui ───── GTK4/libadwaita GUI: sidebar, tabs, splits, |
| 5 | VTE panes, attention rings, desktop notifications |
GUI system deps: libgtk-4-dev libadwaita-1-dev libvte-2.91-gtk4-dev (libadwaita ≥ 1.7; GUI crate only; server/CLI
build without them).
Install the desktop app
| 1 | ./contrib/install-desktop.sh install |
This builds the GUI in release mode and installs signaltty-gui in
~/.local/bin, the desktop entry in ~/.local/share/applications, the
AppStream metadata in ~/.local/share/metainfo, and both icons in
~/.local/share/icons/hicolor/scalable/apps. Make sure ~/.local/bin
is on the desktop session's PATH, then sign out and back in if the
launcher does not refresh. The GUI connects to the signaltty server.
To remove these files:
| 1 | ./contrib/install-desktop.sh uninstall |
To close a workspace, use the close button on its sidebar row, or select it and choose Close Workspace from the main menu. Confirming stops its running terminals and agents. Closing the GUI window leaves them running.
GUI shortcuts (Ctrl+Shift, so plain Ctrl chords reach the terminal):
| Keys | Action |
|---|---|
| Ctrl+Shift+N / Ctrl+Shift+T | new workspace (folder · name · agent) / new tab |
| Ctrl+Shift+E / Ctrl+Shift+O | split right / split down |
| Ctrl+Shift+W | close pane |
| Ctrl+Shift+J | jump to the next pane that needs you |
| Alt+1…9, Ctrl+PgUp/PgDn | switch tabs |
| F9 / F10 | toggle sidebar / main menu |
Server → Workspace → Tab → Pane. Lifecycle (unknown/working/blocked/ done/idle/failed/exited) and attention (none/unread/input_required/ permission_required/warning/error) are independent first-class axes.
Docs: architecture · data model · lifecycle & attention · PTY · terminal research · GTK decision · agents · IPC schema · persistence · security · crates · roadmap & risks · plugins · ADRs.
Plugins live in ~/.config/signaltty/plugins/<name>/plugin.toml
(event hooks + runnable commands); examples in examples/plugins/,
orchestration recipe in examples/workflows/.
Layout
| 1 | crates/signaltty-core domain model (toolkit/async/OS-free) |
| 2 | crates/signaltty-proto signaltty/1 IPC envelopes, methods, events |
| 3 | crates/signaltty-term TerminalBackend trait, headless vt100 backend, |
| 4 | OSC 9/99/777 scanner, sanitizers |
| 5 | crates/signaltty-agent AgentAdapter trait + codex/claude/opencode/ |
| 6 | cursor/generic adapters, hook classification, |
| 7 | session identity, resume commands |
| 8 | crates/signaltty-server daemon: PTY manager, router, events, snapshots |
| 9 | crates/signaltty-cli CLI client incl. interactive attach |
| 10 | crates/signaltty-gui native GUI (sidebar/tabs/splits/VTE, |
| 11 | attention rings, next-unread, notifications) |
| 12 | crates/signaltty-testkit hermetic-server test harness (real PTYs) |
| 13 | contrib/ systemd user unit and desktop integration |
Run as a user service (recommended)
| 1 | mkdir -p ~/.config/systemd/user |
| 2 | cp contrib/signaltty-server.service ~/.config/systemd/user/ |
| 3 | systemctl --user daemon-reload |
| 4 | systemctl --user enable --now signaltty-server |
Development
| 1 | cargo build --workspace |
| 2 | cargo test --workspace # 60+ tests: unit + real-PTY integration + CLI e2e |
| 3 | cargo clippy --workspace --all-targets |
Design rule
The server owns the processes, the terminal backend renders terminal state, agent adapters provide semantic agent state, notifications describe human attention, and the UI helps the user find the work that needs them.