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 global settings with Ctrl+E (roles, MCP servers, skills)
• 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

Orchestrator Mode #

The built-in Admin session can act as a multi-agent coordinator — spawning other sessions, dispatching prompts to them, and reading back their output — all through the thurbox-mcp server.

• create_session spawns a new local-tmux session (optionally on a fresh git worktree) with a chosen role, per-session MCP servers, and skills. Returns a UUID immediately; the TUI processes the queued spawn on its next tick.
• send_prompt types text into a session's pane and presses Enter after a short delay, so the target Claude session receives it as a prompt.
• capture_session_output returns the rendered contents of a session's tmux pane (default 200 lines of scrollback, capped at 10 000).
• Typical loop: create a worker → poll get_session until status is Idle → send a prompt → poll again until idle → capture the output → act on the response.
• Scope: local-tmux backend only. VM and container backends are out of scope; provision those from the TUI and drive them with send_prompt / capture_session_output .

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

Four MCP tools provide programmatic access to templates: list_containerfile_templates , get_containerfile_template , set_containerfile_template , and delete_containerfile_template . 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 global permission presets 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.

Skill Management #

Attach Claude Code skills to sessions at creation time. Skills are symlinked into each session's .claude/skills/ directory and auto-discovered by Claude Code.

• Manage skills globally via Ctrl+E (Settings → Skills tab)
• Select which skills to attach during session creation flow
• Skills are shared across all projects

Session Forking #

Press Ctrl+F to fork the active session. This creates a new session that resumes from the same conversation history, allowing you to explore alternative approaches without losing the original session's context.

Fuzzy Search #

Press / in the project or session list to open a fuzzy search bar. The bar appears directly below the section being searched.

• Project search filters by project name.
• Session search filters by session name, role name, or worktree branch — the three fields visible in each session entry.
• Matched characters are highlighted with accent color. Non-matching entries are dimmed but remain visible.
• j / k jump between matches, Enter confirms, Esc cancels.

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