Home / Docs / Tutorial

Tutorial: your first sessions

The first ten minutes of Thurbox — from an empty screen to two coding agents running side by side, each on its own git worktree, plus the handful of commands you will use every day.

Every screenshot below is the real TUI, captured by driving it through this exact sequence (scripts/demo/record-tutorial.sh in the repository). The paths in them (/tmp/tutorial-home/code/…) come from the throwaway sandbox the capture runs in; yours will be your own ~/code, ~/src, or wherever you keep repositories.

Before you start #

Install Thurbox — both the TUI and the headless companion binary:

    bash
    
curl -fsSL https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.sh | sh

Windows, Homebrew, AUR, winget and Chocolatey are on the Installation page. You also need:

tmux ≥ 3.2 (or psmux on native Windows) — it is what keeps your agents alive when Thurbox is closed
git
at least one coding-agent CLI — claude, codex, agy, opencode, aider, copilot, … Thurbox launches whichever you have; it is not tied to any of them

Nothing to configure. On first launch Thurbox seeds ~/.config/thurbox/ with the agents it knows, the themes, and the interface itself.

1. Launch it #

bash

thurbox

An empty Thurbox: the session list on the left, an empty agent pane on the right — First launch — no sessions yet, and the list says so.

Two panes between two bars: the session list on the left, the agent terminal on the right, and the keys you need on the footer.

2. Add a repository #

Ctrl+N — open the creation flow

The repo picker, with only the interface directory listed — The repo step. On a fresh install, memory holds one row you did not add.

The list is Thurbox's repo memory — the repositories you have used before. The one row already there is your own interface directory, offered because editing the panes is a thing you might want a session for.

To add a repository, press Tab to move to the Add Repo Path field and type a path. ~ is expanded for you.

Typing ~/code/ into the Add Repo Path field — The path field, with the footer naming what each key does from here.

Two ways to finish:

Enter adds the path you typed, if it is a repository.
Tab browses instead — a listing of that directory, marking which subdirectories are git repositories.

The browse dropdown listing ~/code, with a git marker beside two entries — Browsing `~/code`. `↑`/`↓` move; `Enter` on a `●git` row picks it, on a plain folder descends into it.

Either way the repository lands in memory, selected, with the cursor on it — and stays there for next time.

The repository added to the list and selected — Remembered and selected. Adding it once is the last time you type that path.

The rest of what this step can do, all on the list:

Key	Does
`Space`	Select / deselect a repository — select several for a multi-repo session
`w`	Give the selected repository its own worktree
`/`	Filter a long list
`d`	Forget a remembered repository
`Alt`+`P`	Import a folder of repositories at once — type a parent path, press it, and every git subdirectory is added under one header
`Tab`	Move between the list and the path field

3. Give the session its own worktree #

w — worktree mode on the selected repository

The selected repository marked wt for worktree mode — `[wt]` — this session gets a git worktree of its own, not your checkout.

The agent works on its own branch, in its own directory, and your working tree is untouched. Press Enter when the selection is right. Because a worktree needs something to branch from, the next step asks which branch:

The base branch step, offering main — Base branch. Without worktree mode this step does not appear — the session simply runs in the repository as it is.

4. Name it and pick an agent #

Name the session after the work, not the tool — the list reads as a backlog that way. Enter on an empty field accepts the suggested name (the repository's own), so you can press straight through.

The session name step with rate-limit typed — The session name.

The branch name step, prefilled with rate-limit — The branch name, prefilled from the name you just gave.

Then the agent. This is the list from ~/.config/thurbox/agents.toml — the built-ins Thurbox seeds, plus any CLI you have described yourself. With only one agent defined, the step is skipped.

The agent picker listing claude, codex, antigravity, opencode, aider, copilot, vibe, pi and omp — `Enter` creates everything: the worktree, the tmux window, and the agent inside it.

5. You have a session #

The session list with one session, beside a live agent terminal — One session, grouped under its repository, beside the live agent.

the session row, grouped under its repository, with the ⑂ worktree mark, its agent, and a status dot
the agent terminal on the right — a real terminal. Everything you type goes to the agent; Ctrl+O opens the worktree in your editor, and Ctrl+T gives you a shell in the same directory
the status dot tracks the agent through working / blocked / done / idle, reported by the agent's own hooks rather than guessed

Press Ctrl+Q whenever you like: it detaches. tmux keeps every agent running, and relaunching thurbox puts you back where you were — after a crash, a reboot, or a week away.

6. The second session is faster #

The repo picker with the remembered repository listed — Nothing to type: `Space` to select, `Enter`, and through the same steps.

That is the shape of a working day — one session per piece of work, each on its own branch, all alive at once.

Everyday keys #

The authoritative list is F1 (or Ctrl+G), which renders the live key registry, so it can never drift from what is actually bound. Every chord in it is rebindable from that screen; the full reference is Keybindings.

The keybindings help, rendered from the live registry — The help screen is the registry, rendered.

Key	Action
`Ctrl`+`N`	New session
`Ctrl`+`J` / `Ctrl`+`K`	Select the next / previous session
`Ctrl`+`H` / `Ctrl`+`L`	Move focus between panes — the way out of a focused agent
`Ctrl`+`/`	Search sessions and the text on their screens
`Ctrl`+`O`	Open the session's directory in your editor
`Ctrl`+`T` or `F8`	A shell in the session's directory
`Ctrl`+`F`	Fork the session — same repo, branch and agent, with the conversation carried over and the source recorded as its parent
`Ctrl`+`S`	Sync the worktree with its base branch
`Ctrl`+`D`	Delete the session (`Ctrl`+`Z` undoes it)
`Ctrl`+`U`	Restore a deleted session
`Ctrl`+`Y` or `F4`	Theme picker — 36 palettes
`Ctrl`+`,` or `F6`	Settings — `]` for the Interface tab
`F10`	Reload the interface from disk
`Ctrl`+`Q`	Quit, leaving every agent running

Ctrl+/ is the one to remember when the list gets long: it matches names, agents, branches and repositories — and the text on each session's screen, which is how you find the session with the error in it. Matches highlight inside the panes rather than being reprinted.

Search, with the query rate and its match highlighted — Search is a strip, not a modal, so it never covers what it is pointing at.

The same thing from the command line #

thurbox-cli drives the same sessions with no TUI, against the same database — so anything you do here shows up in a running Thurbox within a tick, and vice versa. It is on your PATH inside every session, which is what lets an agent orchestrate other agents (see Orchestration).

It answers in whichever form suits the reader: an aligned table in your terminal, and TOON — a compact, agent-friendly encoding — when its output is piped somewhere. Add --json for the complete record when a script needs to parse it, or --text to keep the table down a pipe.

    bash
    
  
# What is running
thurbox-cli                                # live state: sessions, mail, counts
thurbox-cli session list
thurbox-cli session list --json | jq       # the full record, for a script

# Start one headlessly, on its own worktree branch
thurbox-cli session create --name docs --repo-path ~/code/web-app
thurbox-cli session create --name rate-limit --repo-path ~/code/api-server \
    --agent claude --worktree-branch rate-limit

# Talk to one, and read what it printed
thurbox-cli session send <uuid> "run the tests and fix what fails"
thurbox-cli session capture <uuid>

# Clean up (soft by default — `session restore` brings it back)
thurbox-cli session delete <uuid>

thurbox-cli session list, a headless session create, and the list again — A session created with no TUI running at all — the same database either way.

thurbox-cli config show prints every resolved path, thurbox-cli plugin dir prints the interface directory, and thurbox-cli --help lists the rest (automation, task, message, extension, editor, notify).

Where to go next #

Make it yours — every pane is a Lua file in a directory you own. Ask an agent in any session to change it, or read The Interface. Ctrl+, then ] lists every pane and turns one off; F10 reloads.
Run a fleet — Orchestration and Recipes.
Work on another machine — declare an SSH host or a WSL distro in hosts.toml and sessions run there while the TUI stays local (Configuration).
Configure it — Configuration is every file and knob in one place; Features is why each one behaves the way it does.

The screenshots on this page are generated. Regenerate them from a checkout with scripts/demo/record-tutorial.sh, which drives the real TUI through the steps above.