Session Windows

Every session used to run inside the host's own process. The only way to stop one outside the page was to stop the host and every session with it, and nothing on the desktop said which sessions were running. Now each session on this computer runs in a window of its own, so closing that window stops exactly that session, much as closing a browser window closes one page. The page still manages all of them. Claude Code's desktop app works the same way: sessions side by side in one app, each stopped on its own (Claude Code desktop).

How it works

• A session runs in a child process, in its own window. On Windows, a host listening on the loopback opens each session by starting agent-console-host.exe session through cmd's start (launchSessionWindow). That gives the session its own console, shown in Terminal on Windows 11. The window runs the unchanged Claude Agent SDK driver for that one session (runSessionChild). The host keeps the pairing, the token gate, the event log and the replay to pages, behind the window driver (createWindowDriver), which implements the same Driver interface, so the page's contract did not change.
• The window connects back under a secret of its own. The host listens for windows on a loopback port of its own, separate from the pages' listener, so the window gate is never reachable from the network, whatever address the pages' listener is on. Each window is first admitted by a fresh secret that works once and expires after thirty seconds. The secret reaches the window through its environment, never its command line. The window takes the secret out of its own environment before the session starts, because the session hands that environment to Claude Code and every tool it runs, and a command a repository steers could otherwise read it and speak to the host as that session. The host's own paths reach cmd the same way, so no command line is built from a path.
• The page's commands pass through the host. The host forwards each command to the window holding the session as the page's own Command, and the window runs it with the same handleCommand the host uses. The window sends its driver's callbacks back up (ChildMessage): events, a session opening, a change to the session list, and each command's result or error. A page never talks to a window directly, so pairing stays one credential per computer. The session list is still read on the host, from the transcripts on disk, with each open session's state taken from the events that pass through.
• The window logs the conversation. Each prompt, reply, tool call, permission request and error is printed as it happens (formatSessionLogLine), and a subagent's own conversation is left to the page. The window is a log and a stop control. Typing into the session stays in the page, so there is one composer rather than two that could race.
• Ending the session on purpose ends the window, from either end, and both show it. Closing a session in the page closes the window's socket with the host's own close code (SessionWindowCloseCode.SessionEnded), and the window closes its session and exits. Closing the window, or Ctrl+C in it, ends the session's Claude Code process. The host sees the socket go, marks the session closed, and every page shows it closed at once. A session whose Claude Code process ends on its own ends its window the same way. Resuming a session, or resuming it at an earlier message, opens a new window.
• The host's window stays the computer's log of each session opened and closed, and in which folder. Closing the host's window tells every page the host is stopping, and every session window closes with it.
• A host killed without stopping takes no session with it. A rebuild while developing kills the host rather than stopping it, and so does a crash. Its windows' sockets then drop with no close code, and each window keeps its session running, says so, and tries again every second. The host keeps its windows port and the hash of each open window's secret in the state directory (session-windows.json, written as SessionWindows), never the secret itself, so reading the file admits nothing. A host started later reads that file, listens at once, and for a minute admits each of those secrets once more. A window connects to the port the file now names, and hands the new host every session it holds with its whole log (ChildMessageType.Rejoin). That log leaves out the ephemeral events, the stream's pieces and the running counts, as the host's own log does, so a long session hands back its blocks rather than every piece of them. The host takes each session back as though it had just opened, so every page resets that session and replays it. A window the new host refuses, because its minute has passed, ends its session. A page already reconnects to a host that went away without a word, so the page, the host and the windows come back together.

sequenceDiagram
  participant P as Page
  participant H as Host window
  participant S as Session window
  P->>H: Open a session in a repository
  H->>S: Start the child in a new window, with a secret in its environment
  S->>H: Connect over the loopback with the secret, once
  H->>S: The opening command
  S-->>H: Session open, events
  H-->>P: Events, logged and replayed
  P->>H: Prompt
  H->>S: Prompt
  Note over H: The host is killed by a rebuild
  S--xH: The socket drops, with no close code
  Note over S: The session keeps running
  Note over H: A new host starts, reading the port and the secrets' hashes it keeps
  S->>H: Connect to the port the state directory names, with the same secret
  S-->>H: Rejoin with every session and its whole log
  H-->>P: Session reset, then its log replayed
  Note over S: The reader closes the window
  S--xH: The socket closes
  H-->>P: Session closed

What is deliberately not in it

• No typing in a session window. Two composers for one session would race each other; the window is for watching and stopping.
• No window per session on a remote connection, or off Windows. A host listening beyond the loopback is a remote connection, whose sessions run where nobody sees a desktop, so they stay inside the host. Other platforms keep sessions inside the host until they have an installer (signed host installers).
• No session title kept on the host. The window's own driver reads the title. The host lists every session by the title on disk, which the window's change of the session list prompts it to read again.

Key files

Sources

• Claude Code desktop — work in parallel with sessions — sessions side by side in one app, each stopped on its own.
• Windows Terminal — default terminal application — a new console window opening in Terminal on Windows 11.