Sessions and worktrees

Every session is one conversation with one agent, in one folder. The session list on the left shows all of them.

Each row has the session’s title and a status on its right. Double-click a title to rename it.

What the row shows	What it means
An animated glyph, no words	The agent is working.
Needs input	The agent is waiting for you to answer a question or allow something.
Error	The session hit an error.
Done	The session finished.
Offline	The session is disconnected from its harness.
A short age, such as 4m, 2h or 3d	The session is idle. The number is how long ago it was last active.

Idle rows fade a little after a day, and more after three. Rows that are working or need you never fade. A session whose limit stopped it shows Retry and a time, when Fleet will try again by itself.

Type in Filter sessions to narrow the list. Hover a row for the pin button. Pinned sessions go into a Pinned group at the top. Right-click a row for more, such as Fork, Copy session ID and the project list.

Projects group related sessions, for example everything for one release. Choose the folder-plus button next to New session to make one. Sessions that aren’t in a project sit under Ungrouped.

• Drag a session onto a project, or use the project list in its right-click menu.
• Right-click a project to start a New session in it, Rename it, or Delete… it.
• Deleting a project asks what to do with its sessions. Delete project only moves them to Ungrouped. Delete project and all sessions removes them too.

A new session in a git repository gets its own worktree on its own branch. Your checkout is never touched. Choose Current checkout in the Workspace chip if you want the agent to work there instead.

By default:

• The branch is fleet/ plus words from your first message. With no message it is fleet/session- and a short id.
• The worktree folder is named after the branch and sits in <repo>-worktrees, next to the repository.

Change this under Settings → Folders. Branch prefix replaces fleet, for example with your initials. Branch name, Worktree root and Folder name take templates such as {prefix}/{slug}, and a preview shows the result. A repository can also commit a weave.jsonc file that names branches its way for everyone who clones it.

In the new-session page, a line under the message box shows the branch and base before you start.

Open a row’s menu, or hover it and choose the archive button.

• Archive hides the session from the list. You have a few seconds to undo it. Archiving also ends the session’s terminals and stops any app it started. The worktree, the branch and the conversation stay.
• Restore brings an archived session back. Open Archived at the bottom of the list to find it. The terminals archiving ended don’t come back.
• Delete permanently… removes the session and its history, and Fleet asks first. It also removes the session’s worktree. It doesn’t delete the branch.

Send a message to an archived session and Fleet puts its checkout back if it was cleaned up.

Worktrees add up. Settings → Storage shows how much space they take, and how much of that is in use, needs a look, or could be freed.

1. Choose Preview… to see what would go.
2. Choose Remove to confirm.

Only checkouts of sessions archived for 7 days or more are removed. Fleet always keeps a checkout with uncommitted changes, one that is working, one another session uses, one with an open terminal, and any folder it didn’t make. Branches, commits and conversations stay.

• Reviewing a session: read what the agent changed, run the app, open a terminal.
• Pull requests and GitHub: start a session from an issue and follow its pull request.
• Steer, queue and fork: talk to an agent that is already working.