Threads and sessions
How threads work in GitDB Desktop — workspaces, the three-session limit, Stop versus End session, rewinding and forking, queued messages, and switching CLIs.
A thread is one conversation with an agent. You start, continue and manage threads in the Code view. Each thread keeps its whole conversation, and threads are saved across restarts.
Start a thread
Click ✎ New at the top of the thread list (or press ⌘N on macOS, Ctrl+N on Windows and Linux). The new-thread screen asks "What should the agent work on?". Type your task in the message box and send it — see The composer and status bar for the send key.
Before you send, you can pick the CLI, model and other options from Session settings in the message box — see Agents.
Every thread belongs to one workspace
A new thread is bound to the workspace that's open when you start it — a local folder, or a GitDB repository on a specific branch. The binding never changes.
- If no workspace is open, you can't start a thread. The message box says "no workspace — open a folder or connect to GitDB".
- If you go back to a thread while a different workspace is open, the thread won't run until you switch back. For a local-folder thread the app says "This thread works in" the thread's folder, "the app is currently on" the other one, keeps your message in the box, and offers a Switch to button for the thread's folder. For a GitDB thread it asks you to switch workspace to the thread's repository and branch.
The thread header
At the top of an open thread you'll see its title and a line such as acme / backend ⑂ main · 2 segments · started 14:05 — the workspace, how many agent sessions the thread has used so far, and when it started.
Below it:
- running — a turn is in progress.
- ⧉ Open — opens the thread's workspace in the File view. It only works while that workspace is the one open in the app.
- The added/removed line counts of the agent's changes.
- ■ Stop and ⏻ End session — see below.
The ··· menu next to the title includes Rename, Rewind…, MCP servers…, Skills…, Plugins…, End session and Delete. End session and Delete both ask you to click a second time to confirm.
Sessions and the three-session limit
When a thread runs, GitDB Desktop starts a session: a running copy of the thread's CLI. The session stays open between your messages, so follow-ups start quickly.
At most 3 sessions can run at the same time. The status bar shows how many are running (agent sessions 1/3), and so does the new-thread screen.
You don't have to manage this yourself. When a thread needs a new session:
- The app first closes the sessions of other threads that have had no turn for more than 10 minutes. The thread you're looking at is never closed this way.
- If 3 sessions are still running, it closes the one that was used least recently.
- A session in the middle of a turn is never closed. If all 3 are busy, the new session is refused with a message that "3 of 3 concurrent sessions are already running" and suggests ending one (the thread header's End session) or waiting for one to finish.
A closed session isn't lost work. The thread's conversation line reads "parked (idle) — resumes on the next turn", and your next message picks the conversation up again.
Stop versus End session
| ■ Stop | ⏻ End session | |
|---|---|---|
| What it does | Interrupts the turn that's running now | Closes the thread's session |
| The session afterwards | Keeps running, ready for your next message | Closed; the next message starts it again and resumes the conversation |
| Frees one of the 3 session slots | No | Yes |
| The thread | Unchanged | Unchanged — it is not deleted |
After End session the thread's conversation line reads "session ended by you — resumes on the next turn". If you quit the app, running sessions end too, and the line reads "process ended with the app — resumes on the next turn".
To remove a thread completely, use Delete in the ··· menu.
Rewind and fork
You can take a thread back to an earlier message, or branch a new thread off it.
- Point at one of your messages in the conversation and click ↶ ("Rewind to this message"), or
- choose Rewind… from the ··· menu ("Rewind or fork this thread") and pick a message — newest first.
Rewind
A rewind offers up to three choices:
- Rewind conversation to here — "This message and everything after it will be removed from the thread, and the CLI will resume from the checkpoint before it. Your prompt is put back in the composer so you can edit it and send it again."
- Rewind code to here — puts the files back the way they were at that message.
- Rewind conversation and code — both.
What a code rewind can restore depends on the workspace:
| Workspace | Code rewind |
|---|---|
| Local folder, Claude Code | Available. "Rewinding does not affect files edited manually or via bash." |
| Local folder, Codex CLI | Not offered — only the conversation can be rewound. |
| GitDB repository, either CLI | Available. "Rewinding restores this thread's GitDB workspace to the state recorded at this message — files written through GitDB since then are put back or removed. Anything outside GitDB is untouched." |
The confirm step first asks the CLI (or GitDB) what the rewind would restore, then you click Rewind.
Rewinding a Codex conversation needs Codex CLI 0.148.0-alpha.13 or newer.
Fork
Fork from here creates a new thread: "A new thread is created with every message before this one; this thread is not changed. This message is put back in the new thread's composer, so you can edit it and send it there."
- In a local folder, a fork shares the folder: "Files are not forked, and a code rewind in either thread changes the files both of them see."
- In a GitDB repository, the fork starts with its own, empty set of uncommitted changes. Uncommitted changes in the original thread don't carry over.
Forking a Codex thread needs Codex CLI 0.146.0-alpha.7 or newer. A Codex thread that uses role sub-agents can't be forked.
If a message can't be rewound or forked, its button is disabled and says why.
Sending while a turn is running (the queued message)
You don't have to wait for a turn to finish. While a turn is running, Send queues your message: "it goes out automatically when the turn completes (one queued message per thread)".
The queued message appears in a card above the message box:
| Card | Meaning | What you can do |
|---|---|---|
| Queued | "Sends automatically when the running turn completes." | Edit, Discard |
| Sending… | "The running turn completed — this message is being sent." | Nothing — it's on its way |
| Held — not sent | The turn didn't complete normally (for example you pressed Stop, or it failed), so the message was held instead of sent. The card says why. | Send now, Edit, Discard |
Only one message can be queued per thread. While one is waiting, Send is disabled until you send, edit or discard it.
- Edit moves the queued text back into the message box. It's refused if the box already has text in it, and for a queued message that carries images.
- Deleting a thread also deletes its queued message — the confirm step says so ("Click again — its queued message is deleted too").
Switching CLIs in the middle of a thread
In a GitDB repository, one thread can use both CLIs. Open Session settings in the message box and pick the other CLI under Run the next turn with. As the menu explains: "Switching arms keeps this thread. The other CLI gets a handoff prefix built from the transcript; its own thread id is kept so you can switch back."
In a local folder, a thread stays on the CLI it started with. The other CLI is disabled with the reason: "local thread runs on Claude Code only — switching CLIs mid-thread (mixed mode) needs a gitdb workspace" (or "Codex CLI only"). To use the other CLI on the same folder, start a new thread.
Changing the model mid-thread works in both kinds of workspace — see Agents.
After you switch a GitDB thread to Claude Code, its first message there can't be a slash command, because it carries the handoff. Send a plain message first — see Slash commands.