Start and organize a session
Open Code → New session, choose a folder, and check the branch, model, and permission mode before sending the first message. The first message attaches the workspace to the session. To work in a different execution environment, start another session and choose its destination first. Give each session a specific purpose, such as investigating a failing checkout test or reviewing an API change. Use the session’s sidebar menu to rename it, pin work you return to frequently, or archive completed work. Archived sessions remain available in Archived. Deleting a local session removes its saved history from this computer; read the confirmation before continuing. Use Filter sessions beside the search field to narrow the list by Status, Project, Environment, or When. A dot marks a session that finished or failed while you were away until you open it, and a pencil marks a session with an unsent draft. Click a project’s header to collapse its group; Archived starts collapsed. To act on several sessions at once, Shift-click or Cmd-click (Ctrl-click on Windows and Linux) them, then pin, archive, or delete them from the selection bar. Chats support the same selection for deleting. A project’s … menu can pin the project, start a new session in its folder, archive its sessions, or remove it from the sidebar. Removing a project hides it on this computer; it does not delete sessions or files. A new conversation does not create a new copy of the repository. If two tasks need to edit the same project independently, use separate worktrees.Add project context
Mention relevant file paths with@, or attach the failing test output so the agent has the error to investigate. The composer accepts file selection, drag-and-drop, and pasted attachments, including specifications and screenshots. Image input requires a model that supports it.
Give the agent a checkable request
Include the observed behavior, expected behavior, and a way to verify the result. File names and error output help the agent begin with the relevant code instead of guessing where to look:The checkout returns 12 for three items priced at 12 each. Read @checkout.js and @checkout.test.js. Add a failing test for a total of 36, fix the calculation, and run npm test. Keep the public function signature unchanged.Select the intended item from the
@ suggestions before sending. Attach a design or screenshot when the task depends on appearance; explain which part matters. Some document formats require a matching skill, and the app warns you when that skill is inactive.
For a screenshot, open Mark up the image on its thumbnail to point out the relevant control or region. Review the edited image, then choose Apply. The marked image replaces the attachment for that message.
Follow a running task
The timeline records the agent’s responses and tool activity as the task runs. Each tool card shows the action and its result: a file read, a command, or a response from a connected service. For the checkout example, inspect the failing test output first, then compare it with the result after the calculation changes. Click a tool card to expand the command and its output. When the app requests approval, inspect the proposed action before approving or denying it. Answer the agent’s questions in the session, and send further instructions if the task needs to change direction. Sending a message during a run follows Settings → Composer → A message typed during a run. Queue holds the message until the run finishes. Interrupt delivers it at the next model turn, so it can change the agent’s next step. To stop the active turn, choose Cancel run. When a turn ends, the composer can suggest the message you are likely to send next as dim text. PressTab to accept it, then send it as usual; typing anything else hides it. Turn suggestions on or off in Settings → Composer → Suggest a next prompt.
Queue, redirect, or stop
Use Queue for a follow-up that depends on the current result, such as asking for a summary after the tests finish. Use Interrupt when the next action should change, such as correcting a file name or narrowing the scope. An interrupt is delivered at the next model turn; inspect the timeline to see what has already run. To change a message you queued from the composer, use the buttons under it before it is sent: Edit message moves it back into the composer, which must be empty first, and Remove from queue deletes it. PressingUp in an empty composer also takes back the last queued message.
Canceling a run stops the active turn. Check Session changes afterward to see which edits remain, then decide whether to continue from those files or revise them. Canceling is not a Git rollback.
Ask a side question
To ask about a local session without interrupting it, choose Side chat in the session header or pressCmd + Shift + A (Ctrl + Shift + A on Windows and Linux). You can also type /ask followed by your question in the main composer, or select text in the session, right-click it, and choose Ask about this.
A side chat reads the session’s conversation and can read files, but it cannot edit files or run commands. Nothing in it reaches the agent unless you copy an answer into the main composer and send it. Closing a side chat deletes it.
Return to earlier work
To return to earlier work, use Search sessions to find a session by name or transcript text. Select it to reopen the conversation and continue with its saved workspace. Use Search this session to find a result within a long transcript. To keep a copy outside the app, open a session’s or chat’s sidebar menu and choose Export as Markdown… or Copy as Markdown. For the open session or chat, pressCmd + Shift + S (Ctrl + Shift + S on Windows and Linux). File → Import from Markdown… reads an export back in: a chat becomes a conversation you can continue, and a session opens as a new draft with the export attached.
Revisit a decision
Pin a useful message and open Pinned to find it later. To explore another approach, choose Fork from here on an answer after the run finishes. It copies the conversation up to that point into a new session and leaves the original unchanged. This forks the discussion; use a Git branch or worktree separately if the files also need to be isolated. Restart from this message and Edit and restart from here replace the later conversation. The confirmation may also offer to restore files changed since that point. Review the listed files and choose deliberately: keeping a transcript, replacing later messages, and restoring repository files are different operations.Search finds previous sessions so you can return to their conversation and results.