Features

Session Orchestration #

Run multiple Claude Code instances side-by-side, each in its own tmux pane. Sessions persist across crashes, restarts, and even multiple concurrent Thurbox instances — tmux keeps them alive in the background.

• Restart a session with Ctrl+R to pick up new role permissions while preserving conversation history via --resume
• Each session displays elapsed time ("Waiting 45s", "Idle 2m")
• Clickable URLs highlighted in terminal output
• Select text with mouse drag, copy with Ctrl+C , paste with Ctrl+V . With no selection, Ctrl+C sends SIGINT to the active session.
• Toggle a shell pane alongside the Claude session with Ctrl+T
• Recover sessions externally at any time with tmux -L thurbox attach

Project Management #

Organize work into projects, each with its own sessions and settings. The two-section left sidebar shows all projects on top and the active project's sessions below.

• Multiple repositories per project — first repo becomes working directory, rest passed via --add-dir
• Edit projects on the fly with Ctrl+E (name, repos, roles, MCP servers) without losing running sessions
• Soft-deleted projects and sessions can be restored via Admin session or MCP API
• Built-in Admin project (pinned at index 0) provides conversational Thurbox management via MCP

Scheduled Commands #

Press Ctrl+P to schedule text that will be sent to the active session after a configurable delay. Useful for queuing follow-up prompts or pacing multi-step workflows.

• Modal with two fields: command text and delay in minutes. Tab switches fields, Enter submits, Esc cancels.
• Dual-track execution: a tmux external timer fires independently of Thurbox (survives crashes), and an app-level tick loop provides a safety net. Whichever fires first prevents duplicate execution.
• Scheduled commands are persisted in SQLite and can be managed programmatically via four MCP tools: schedule_command , list_scheduled_commands , get_scheduled_command , cancel_scheduled_command .

Git Worktrees #

Optionally spawn sessions inside git worktrees for branch isolation.

• When creating a session ( Ctrl+N ), choose "Worktree" mode to select a base branch and name a new branch
• Thurbox creates the worktree and launches Claude inside it
• Press Ctrl+S to sync all worktree sessions with origin/main
• On rebase conflicts, Thurbox automatically sends a resolution prompt to Claude
• Closing a session automatically removes the worktree
• Worktree sessions show the branch name in the terminal title and session list

Worktree storage

Worktrees are created at <repo>/.git/thurbox-worktrees/<sanitized-branch> , where / in branch names is replaced by - .

Worktree Sync #

Ctrl+S synchronizes all worktree sessions in the active project with their upstream default branch.

• Sessions are grouped by repository to avoid git lock contention. Different repos sync in parallel.
• Per-worktree: stash uncommitted changes, fetch, rebase origin/main , stash pop.
• Stale .git/index.lock files from crashed git processes are automatically cleaned up before syncing.
• Runs on background threads — the TUI remains fully responsive.
• Results shown per-session: synced, conflict (sent to Claude for resolution), or error.

Container Sessions #

Run sessions inside Docker or Podman containers for lightweight isolation. Choose "Container" in the session mode selector.

How it works

• Thurbox builds a container image from a Containerfile template
• Runs the container with optional firewall-restricted network egress (nftables/iptables allowlist)
• Spawns the Claude session inside the container
• Auto-detects runtime (Podman preferred, Docker fallback)
• Containers survive Thurbox restarts

Templates

Templates are stored at ~/.local/share/thurbox/admin/containerfiles/ . A default/ template (Debian Bookworm-based) is seeded on first run. It installs tmux, git, iptables, Claude Code, and creates a dedicated thurbox user (UID/GID 5000). Add custom templates by creating folders with a Containerfile and any support files.

A TUI picker modal lets you choose a template when creating a container session. If only one template exists, the picker is skipped.

Template management via MCP

Six MCP tools provide programmatic access to templates and per-project container configuration: list_containerfile_templates , get_containerfile_template , set_containerfile_template , delete_containerfile_template , configure_project_container , and get_project_container_config . Template names are validated to prevent path traversal.

Default container configuration

VM Sessions #

Run sessions inside QEMU/KVM virtual machines for full OS-level isolation. Choose "VM" in the session mode selector.

VM specifications

Requirements

• qemu-system-x86_64 with /dev/kvm support
• genisoimage or mkisofs (cloud-init ISO creation)
• ssh-keygen , rsync

Session restoration

VMs survive Thurbox restarts. On restart, Thurbox discovers VMs from the database, verifies the QEMU process is still running via SSH probe, and re-adopts the tmux session inside the VM. If a VM has died, Thurbox re-provisions a new one with --resume to preserve conversation history.

CoW overlay and cloud-init

Each VM gets a QCOW2 copy-on-write overlay referencing the shared base image. The base image is never modified — all writes go to the per-VM overlay, which grows on demand. VMs are provisioned via cloud-init (nocloud format) with a thurbox user, SSH key injection, and an optional custom setup script.

SSH port allocation

VM SSH ports start at 22200 and increment. Thurbox probes candidate ports to skip those already bound by orphaned QEMU processes, scanning up to 100 ports.

VM image management via MCP

Three MCP tools manage the base image cache: list_vm_images , download_vm_image (HTTPS-only), and delete_vm_image . Filenames are validated to prevent path traversal.

Role System #

Define per-project permission profiles that control Claude's behavior. Each role specifies:

• A permission mode ( default , plan , acceptEdits , dontAsk , bypassPermissions )
• Lists of allowed and disallowed tools with scope patterns like Bash(git:*)
• Optional system prompt text appended to Claude's prompt
• Optional environment variables injected into the session

Manage roles from the TUI via Ctrl+E or programmatically through the MCP server . See Role Configuration for the full guide.

Responsive UI #

Three layout tiers adapt to your terminal width:

• Scrollback with Shift+arrows / PageUp / PageDown / mouse wheel
• Non-modal error messages in the status bar
• Vim-inspired keybindings throughout
• Tri-state focus system (Focused, Active, Inactive) with visual border feedback

Session Persistence #

Sessions run inside a dedicated tmux server ( tmux -L thurbox ) and survive crashes, restarts, and multiple concurrent instances.

How it works

• Sessions spawn as tmux windows. The tmux pane keeps running regardless of Thurbox's lifecycle.
• On shutdown ( Ctrl+Q ), session metadata is saved to SQLite. Thurbox detaches without killing sessions.
• On restart, Thurbox discovers existing sessions from tmux, matches them to persisted metadata, and adopts them with terminal content intact.
• External recovery is always possible via tmux -L thurbox attach .

Close vs Quit