claude-fleet

claude-fleet shows every Claude Code session running on your machine in one pane: what each one is about, whether it is busy or waiting on you, its git branch and uncommitted work, how long it has been idle, and how much context it would send again. From the same pane you write a handoff, export the conversation or close the sessions you no longer need. It is for people who keep several sessions open or run parallel agents in worktrees.

What it does

• A status line, always on, with the number of sessions, how many are busy and how many need you. It stays empty while only one session runs.
• /fleet opens a pane that refreshes every 5 seconds. Each row shows a short generated title instead of the folder-based name, the status (busy in yellow, waiting on you in red), the project folder, the branch with uncommitted files and commits ahead or behind, the time since the last activity and the context size. Worktrees of the current repo with no session in them get a row too, and a conversation resumed in two terminals is marked ×2.
• Resume value. Each session is marked in progress (●), finished (◐) or light (○): worth resuming, worth a handoff before you close it, or safe to just close.
• Cold sessions. The context column is how many tokens the session’s next message sends. After an hour idle, fleet marks it cold: the prompt cache has expired, so resuming caches all of it again at full price.
• Handoff (h, or /fleet handoff [pid|name]): a short summary file in the session’s folder with the goal, status, decisions, next steps, key files and gotchas. A fresh session continues from it in about 3k tokens, and the original stays resumable.
• Save (s, or /fleet save [pid|name]): the whole conversation as Markdown in the session’s folder, with your messages, Claude’s replies and one line per tool call. With no argument it saves the current session.
• Close (x twice within 10 seconds, or /fleet kill). /fleet kill targets the sessions it considers safe to close: idle and either cold with a finished or light value, or idle for more than a week and not in progress. /fleet kill all targets every idle session except yours. Both only list the targets the first time and act if you repeat the command within 60 seconds. Add --handoff or --save to export each session first; one whose export fails stays open.
• Copy resume (c) puts cd <folder> && claude --resume <id> on the clipboard.
• In your own session. Past 300k tokens of context, a band above the prompt offers to write a handoff, clear the session and continue from it; “Later” asks again 100k tokens on. /exit pauses once when the session is in progress or holds more than 100k tokens. A toast tells you when another session starts waiting on you or finishes its work.
• /fleet list, /fleet stale, /fleet retitle and /fleet help print text instead of opening the pane, and also work in claude -p.

Install

Needs Claude Code 2.1.287 or later, plus macOS or Linux and git. fleet calls ps, kill, head and tail, so it does not run on Windows.

There is no marketplace: you clone the repository and load it as a plugin folder.

git clone https://github.com/Dubbus/claude-fleet
claude --plugin-dir claude-fleet

To load it in every session instead, set CLAUDE_CODE_PLUGIN_DIRS=/path/to/claude-fleet in your environment. The plugin is called fleet: run /fleet to open the pane, which takes the keyboard (arrows to select, Esc to hand it back to the prompt, a click to take it again). To try every key on made-up sessions first, start Claude Code with CLAUDE_FLEET_DEMO=1 claude --plugin-dir claude-fleet. Demo rows have no transcripts and are not real processes, so save, handoff and close do nothing.

How it works

Where the list comes from. Claude Code keeps one small JSON file per running session in ~/.claude/sessions/. fleet reads those files and keeps only the process id, folder, name, status, session id and last update. The author points out that the other fields include auth tokens, and the parser never uses them. It then runs ps to drop entries whose process has died. That folder is internal to Claude Code, not a public API: if a release moves or reshapes it, fleet says so in the pane, the status line and /fleet list instead of showing an empty list, and CLAUDE_FLEET_REGISTRY points it at the new folder.

What it reads. With the pane closed, it re-reads only the session files every 15 seconds, for the status line. While the pane is open it does a full scan every 5 seconds: git status --porcelain=v2 --branch in each distinct folder, git worktree list in your current one, and the last megabyte of each session’s transcript in ~/.claude/projects/, where it takes the token usage of the last reply. A transcript is read again only once it has grown. After each of your turns it also checks your own session’s context size the same way.

Model calls. Titles and resume values come from Claude Haiku, called through your own Claude Code login, so they count toward your usage. Each call is small: the first three and latest two requests, the end of the last reply and the idle time, capped at 5,000 characters, with a reply of up to 80 tokens. It runs only during full scans (the open pane, or /fleet list, stale, save, handoff, kill and retitle), for at most two untitled sessions per scan, and the result is cached in the plugin’s store until the transcript doubles in size. Sessions you named with /rename keep their names and are never sent. /fleet retitle forgets every cached title and titles all unnamed sessions at once.

A handoff sends the conversation as text (your messages, Claude’s replies and one line per tool call, cut to 400,000 characters by trimming the middle; the author estimates about 100k tokens) to Claude Sonnet, again through your login. It happens only when you ask for one, which includes each session in /fleet kill --handoff. Saving makes no model call. Nothing else leaves the machine: the module makes no network requests of its own and has no dependencies.

What it writes. Handoffs go to claude-handoff-<title>-<date>.txt and saves to claude-context-<title>-<date>.md, in the session’s own folder, numbered when the name is taken. Both can contain secrets and the commands Claude ran, so fleet runs git check-ignore and warns you when the file is not git-ignored. Generated titles live in the plugin’s store. Exports refuse transcripts over 80 MB.

Closing. fleet closes a session by sending its process a plain kill (SIGTERM), after checking with ps that the pid still belongs to a Claude process, since pids get reused. Only idle sessions qualify: never yours, never busy ones, never ones waiting on you. Nothing is deleted: the transcript stays on disk and claude --resume brings the conversation back.

Your own session. fleet never types into another session. Its prompt and command calls only act on the session you are in: “Hand off and start fresh” runs /clear, then submits a first message asking Claude to read the handoff file. /fleet handoff --fresh does the same as a command, and /fleet handoff --exit writes the handoff and then exits. Set CLAUDE_FLEET_HANDOFF_AT to move the 300k threshold, CLAUDE_FLEET_EXIT_CHECK=0 to drop the /exit pause and CLAUDE_FLEET_NOTIFY=0 to silence the toasts.

Limitations

• The author tested fleet on Claude Code 2.1.286 and 2.1.287. Mod events and methods, and the internal session folder it reads, can change between versions.
• The /exit pause catches /exit only, not ctrl+c.
• The cold mark appears after an hour idle. The code notes that the prompt cache lasts 5 minutes by default on the API and an hour on some plans, so with a 5-minute cache a session goes cold well before fleet marks it.
• The author documents it only in the terminal.