Sessions
What it is
A session is a conversation with an agent (like Claude Code or Codex) that works in one project's folder. Sessions are what actually write code and change files.
There are two ways a session can be looked after:
- Hand to Q: sessions Q opened, or that you handed to Q. Q keeps track of their progress.
- I'll look after it: you talk to it directly, just like using Claude Code or Codex on their own.
Either way, you can open it and look, or chime in, at any time.
When to use it
- A small job, a question, or something you want to walk through step by step yourself: open a session yourself.
- Work Q handed out: you don't need to open anything; just click in to look.
How to use it
Opening a session
Press ⌘N, or click the "+" next to a project. Choose these, write a sentence about what to do, and press Return to start:
- Who looks after it: hand it to Q, or look after it yourself;
- Which task it takes: create a task and then do it, pick one from the board, or no task;
- Which agent, which model, and how hard it thinks (thinking effort);
- Which computer it runs on (when several computers are connected).
The model starts with the preset you marked as "default", and you can still change it when opening the session. See Usage & quota.
Changing model and permissions
Under the input box you can change the model, thinking effort and permissions.
- Permissions: what the agent has to ask you about first. These follow each agent's own modes; you can also pick "Allow everything" (it asks nothing).
- Fast mode: can be turned on when the model supports it. Replies come faster and use more.
- Switching agents midway: just pick the other agent's model (Claude Code to Codex, or the reverse); it switches from your next message. The conversation so far and the linked task come along, and a line in the chat says what came along; anything that looks like a secret is masked first. When quota is running low, the session also offers: "Continue on Codex?"
Talking to it while it runs
There are three ways; pick one as the default (Settings › General › What you send while a session is running):
- Slip it in: added to this turn without interrupting it;
- Wait for it: sent once this turn ends. Queued messages can be edited or deleted, and you can also click "Send now";
- Interrupt: stops this turn and takes your message right away.
Seeing what it's doing
- Reading files, changing files and running commands are grouped together, with a plain-language summary of what it did; click any step to see the details.
- When a turn is finished, it folds into one line: "how long it took · what it changed".
- To show everything, or only the results, change it under Settings › General › Process in sessions.
- For things like comparing options, numbers or flows, the agent can draw a page right in the chat for you.
When it needs your OK or asks you something
When the agent wants to do something that needs your OK, or asks you a question, a card appears in the session, the left sidebar shows a yellow badge, it goes into "Needs you", and a small box pops up at the bottom right of the screen. See Q › Needs you.
A few kinds of commands are blocked outright, with the reason written down: reading the raw text of keys, changing your network and proxy settings, and installing or changing the agent program itself.
Seeing changes
- "See changes" under a reply: only the files changed in this turn.
- "+added −removed" at the top of the session: how much this task changed in total.
- Click a line in the changes to write a note; collect them and hand them to the session together (with file and line number).
- To look in an editor: from the top of the session, open it in VS Code, Cursor, Terminal or Finder with one click.
Forking and rewinding
Under the last reply of each turn there are "Fork" and "⋯":
- Fork: opens a new session with the conversation up to this message. By default it gets its own copy of the code, so each side changes its own. Use it to try a different approach.
- Rewind: in "⋯". You can rewind just the conversation, or the conversation and the files together. Before rewinding it lists which files will be changed back, and you can undo the rewind once. Anything already committed isn't undone.
Where the work happens
A task usually works in its own workspace: a separate copy of the code made for this task, so several tasks can run at once without clashing. Research tasks that only look and don't change anything work right in the project's original folder.
If the project folder has changes you haven't committed, it stops first and asks you where this task should work. Your changes are left exactly as they are.
Terminal, and taking over in a terminal
- You can open a terminal under the session (⌃`), right in this session's folder.
- To take over yourself: click "⋯ → Take over in terminal" at the top of the session. The agent stops first, and in the terminal you talk to it and change code directly. When you're done, click "Hand back", and it continues the same conversation, knowing everything you said in the terminal.
Dev build
When a session works on UI, it starts a "dev build" (the project up and running) and screenshots it to compare with the prototype. It can only use a start command you've approved. It stops automatically when the task is accepted or taken back, or after 30 minutes without use.
(Register the start command once under Project settings › Run & preview. See Prototypes & acceptance.)
For a dev build running on another computer, click "Open on this computer" to see it in the browser on the computer in front of you.
Tips for the input box
- @ refers to files, sessions and tasks; # finds PRs; / runs commands, like
/usageto see quota,/handoverto have the session hand over to a new one, and/forgetso nothing you say this time goes into memory. - Next-sentence suggestions: the input box suggests a sentence; press Tab to use it.
- ⌘L: select part of a reply, code or change, and put it as a quote into any session's input box.
It looks after itself
- Stops when idle: when a session has been idle for 15 minutes, the agent process stops automatically to save memory. It picks up again when you say something, and the conversation is still there.
- Session handover: when a conversation gets too long, the session writes a handover itself and a new one carries on. "What was tried and why it was dropped" is always included. You can also type
/handoverany time. - Redoes the turn if the engine crashes: if the agent quits unexpectedly, QU reconnects the original conversation and redoes the turn from the start. After updating the app or restarting the computer, the turn that was running continues automatically.
- Push each turn to the task branch: when turned on, after each turn the commits made so far are pushed to the task branch on the remote (a code host like GitHub). If the computer goes offline, another computer can carry on. (Turn it on in project settings; you're asked the first time it pushes.)
Done / Won't do
At the top of the session there are these two buttons:
- Done: the task this session took counts as accepted by you, is merged into main, and moves to "Done"; the session moves to session history. If tests failed or merging hit a conflict, it doesn't count as done: the task stays in "Waiting on you" with the reason written down, and one click on "Have the session fix it" sends it back to work.
- Won't do: the task moves to Archived, marked "Won't do"; the session stops and moves to session history.
You can undo for a few seconds after clicking. If a session without a task is closed without clicking either button, you're asked: "Add it to the board?"
Archiving only puts it away; it doesn't delete it. Unarchive it any time to keep chatting.
FAQ
How is using Claude Code in QU different from using it directly in a terminal? It's the same Claude Code: the same models, tools and plugins. What QU adds is the board, Q, the approval box, forking and rewinding, and so on.
Do sessions stop when I close the window? No. Sessions run in a background service, and closing the window or updating the app doesn't interrupt them. See Settings › Running with the window closed.
Whose account do sessions use? Yours. Usage counts against the Claude / ChatGPT account or API key you signed in with.
Can a session get others to help at the same time? Yes, by calling in helpers or subagents. See Helpers & subagents.