Skip to main content
Sessions shows the agent work happening now. Every surface that runs an agent - an editor, a desktop app, a terminal - runs a session of Claude Code or Codex, and Sessions lists them together. It opens to the list with nothing selected; selecting a row shows its activity beside it.

The list

Each row shows whether the session needs you, whether it is working, the model it runs with the provider’s logo before it, and the project it started in. A project that belongs to one of your agents shows as the agent’s name and icon. The narrow column at a row’s left carries its state: Under Reduce Motion the indicators stand still.

Order

Choose the order in Settings > Sessions:
  • Latest turn (the default): a session rises when it appears or someone writes to it, and stays in place while it works.
  • Most recent activity: every step of a working session lifts it.
  • Started: nothing moves, and new sessions arrive on top.
A row that changes place slides there, and the order holds still while the pointer is over the list.

Nested sessions

Sessions a live session spawns - its subagents, and the agents it consults in other projects - appear nested under it. A Claude subagent is a session of its own, titled by its task, with its own feed; its steps also show once in its parent’s feed. Filters choose only top-level sessions; whatever is nested under a session shown stays under it. The toolbar holds:
  • Working (bolt): only sessions working, watching or needing input, with their count.
  • Unread (inbox tray): only unread sessions. With both on, either kind shows.
  • Background (terminal): headless and scheduled runs no interactive session launched, such as jobs a project’s service starts. Off by default.
  • Pinned (pin): pinned sessions as their own block above the list. On by default.
  • Archived (archive): archived sessions. Off by default.
  • The period: Last hour, Last 24 hours (the default), Last 7 days or All time. Sessions that are working, watching or need input show whatever the period.
  • The agent filter, listing your agents with their icons.
  • Search, by session title and agent or project name.
While any session needs input, a count appears at the toolbar’s right end. In a narrow window the controls shrink to their icons before anything moves into an overflow menu. The controls keep their setting across launches. A session the tasks service started to work a task carries a Task tag, and its header offers Show task. A Codex app thread appears while its turn runs and for a short while after, labelled by its last activity.

Pin, archive and read

A session’s header holds, as icon buttons:
  • Mark as read / Mark as unread: an inbox tray, with an accent dot while unread.
  • Pin: keeps the session above the list.
  • Archive: hides it unless Archived is on. A working session cannot be archived, archiving makes a session read, and writing to an archived session brings it back.
None asks for confirmation, since each undoes. How a session becomes read is your choice in Settings > Sessions: Manual, where only your next turn or Mark as read makes it read, or On open, where selecting it does. Only interactive sessions become unread; background runs, task sessions and nested sessions never do. These marks are AgentKit’s own, kept in your database; Claude and Codex do not see them. Without a reachable database the list still shows, without marks. Sessions are never deleted from AgentKit.

The session header

Beside the title stand the session’s facts, its model and metrics, and a quiet ID tag; pressing it copies the session’s bare id. The controls on the right:
  • New session: starts a new session with the same agent in the same harness. ⌘N does the same.
  • Open in the source app, for a session started elsewhere.
  • Claim session, for a session started elsewhere that no other process runs, so you can talk to it here.
  • Read, Pin, Archive and Close.
Click a session’s title to rename it. A Claude session’s name shows everywhere Claude shows it, the editor included; a Codex session’s name goes to Codex’s own thread name. A rename asked while the session works applies when it stops. A Claude session AgentKit runs on this Mac can be made Eternal from its header: it is never closed for being idle, it is continued at every launch, and Claude compacts its context once it fills to a set share, 40% unless Settings > Sessions chooses another.

The feed

A session’s feed reaches its whole history; older parts load as you scroll back. Consecutive tool calls fold into one line that opens onto a step per call, and Expand steps opens them all. A thinking block shows as a closed Thinking line, and a compaction of the context as a quiet marker. Under each message stands its time and, while the pointer is over it, Copy.

File preview

Click a file name in a Write or Edit step, or an existing path in a message, and the file opens over the session: Markdown and plans, code, JSON, logs, images and PDFs. Its top bar shows the path, Copy, Open With, Show in Finder and Close. ⌘-click a file on this Mac to show it in Finder at once. An agent’s documents in the database - its context, routines and assets - open in the same preview with their kind, name and version, and Copy and Download.

Run a command block

A code block the agent marks as a shell command (bash, sh or zsh) carries Run and Copy at its top right. Run is your consent: the command runs where the session runs, in its working directory on this Mac or on its server. Its output appears under the block as it comes, with Stop while it runs and the exit code at its end. The agent takes the command and its output in with your next message, with nothing else added to the conversation.

Widgets

In the sessions AgentKit runs, an agent can answer with AgentKit’s widgets as well as text. Each widget does one fixed thing, says beforehand exactly what its press will do, and your press is the consent. Its result reaches the agent with your next message. Other surfaces show a widget as plain code. The first widget is Secret: a masked field and Save, which stores the value in the agent’s vault. The value never enters the conversation; the agent learns only that it was saved.

Talk to a session

AgentKit is a surface of its own. A session started from an agent’s page runs in the agent’s folder, and its panel ends with a composer. Writing to a session after it ended continues it. AgentKit writes only to the sessions it started or you claimed. Any other session stays readable here and continues only in the surface that started it. AgentKit ends a session’s process after a few idle minutes so it can be continued elsewhere without two writers; your next message continues it.

The composer

A box with your text on top and one row of controls under it: the mode on the left, the model on the right, then Send.
  • Mode: for Claude, every mode Claude has, each with a line on what it does; for Codex, its three approval choices, Ask for approval, Approve for me and Full access. A new session starts in the default from Settings > Claude or Codex; a session continues in the mode it last ran in.
  • Model: the models the harness offers, and an effort slider over the levels the model supports.
  • Send / Stop: while a turn runs, Send becomes Stop when the box is empty. A message sent during a turn shows as queued and joins the running turn at its next step.
  • Pasted or dropped images, screenshots included, join the message as attachments.
When Claude or Codex asks to run a command or change a file, the panel asks you.

Dictation

The microphone beside Send starts listening on one press and stops on the next, and so does one tap of the dictation key, right Option by default. Text appears at the cursor as you speak, dimmed while it is still being recognised. Send while listening waits for the last words and sends; Escape stops and keeps the text. Listening stops by itself after 30 seconds of silence. Dictation uses Deepgram with your own key, set in Settings > Transcription. macOS asks for the microphone on the first press.

Voice mode

With voice mode on in Settings > Voice, a microphone stands left of the composer. Pressing it starts a call with a realtime voice model, Gemini Live or GPT Live, with your own key. The voice hands what you said to the session as your message and tells you the agent’s reply in its own words; you can keep typing throughout. See Talk to an agent by voice.

Where a session runs

A session runs on one of its agent’s nodes. For an agent on more than one node, New’s menu holds a Run on section: This Mac and each server, an unreachable one greyed. The choice is remembered per agent. A session on a server runs there, its transcript staying on the server; its row and header show a server glyph after the agent’s name. A lost connection is one quiet line, and your next message continues the session.

After a restart

Sessions AgentKit runs continue by themselves after AgentKit restarts. At launch AgentKit sends each one that was working, watching or waiting on something it armed a short phrase saying AgentKit restarted and that work in progress is to be picked up again, and then says in a toast how many it continued. Settings > Sessions holds the phrase and a switch that turns this off. Sessions of other surfaces are never written to. If a harness has no signed-in account, the session’s panel says so with a Sign in button rather than the harness’s raw error.