Your first session

A session is one Claude Code conversation with one git worktree and one branch attached to it. This page walks the whole life of one.

Creating it costs nothing

Press Cmd N, pick a repository, and the chat opens immediately. At this point Fleet has created a record and nothing else: no directory, no branch, no agent process. That is why it is instant, and it is also why an empty session is safe to abandon.

The first prompt is what provisions

Type what you want and send it. Provisioning then happens in order, and you can watch it in the status strip:

1. Fleet fetches the base branch from the remote and creates your branch from origin/<base>.
2. git worktree add puts a fresh checkout on disk at that branch.
3. Any files the repository asked for, such as .env.local, are copied in from your main checkout.
4. The repository's setup script runs, if it has one.
5. The agent process starts, and your prompt is delivered.

Because the branch is created after you have said what you want, it can be named after the work. fleet/fix-webhook-retry rather than fleet/session-4.

Two consequences of that ordering are worth knowing. Fetching, rather than pulling, means your own checkout of the base branch is never moved to serve a background session. And if the fetch fails, because you are offline or the repository has no remote, Fleet falls back to your local base branch rather than refusing to start.

While it runs

The transcript shows the agent's messages, its thinking, and every tool call as a card. Tool cards collapse: a diff, a file read, a command and its output.

The sidebar carries status by colour and by shape, and the colours mean one thing each.

• Cyan is running.
• Amber is blocked on you and needs an answer.
• Green is finished or accepted.
• Red is failed or refused.

Amber is never decoration anywhere in Fleet, which is what makes a blocked agent findable at a glance in a rail full of sessions.

When it stops to ask you something

Depending on the mode, three things can interrupt a turn and all three are yours alone to answer:

• A permission request for a tool it wants to use.
• A question, when the agent needs a decision only you can make.
• A plan, when the session is in Plan mode and the agent is proposing what to do.

Auto mode allows tool use without asking, but it never auto-answers a question and never auto-approves a plan. Nothing in Fleet does.

Reading what it did

Open the review panel with Cmd D. It shows the diff against the base branch: committed work and uncommitted work together, because either alone is still something to review.

Select lines and leave a note. Notes collect into a draft, and sending the draft delivers all of them to the agent as one prompt, quoting the code each one is about. That is a better round than paraphrasing three problems into a chat message.

Ending it

There are four different endings and they are not interchangeable:

• Merge into the base branch. Runs from your main worktree, and refuses rather than stashing anything on your behalf.
• Push and open a pull request with gh. When that pull request is merged, Fleet closes the session and reclaims the worktree, and keeps the branch, the record and the transcript.
• Archive. Reversible. Reclaims the worktree, keeps everything else, and can be restored later with the worktree rebuilt at the same branch.
• Delete. Not reversible, and the only thing that removes the transcript.

Next

• Worktrees and branches
• Permissions and modes
• Checkpoints, for putting a bad turn back