> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> A live monitor of every Claude and Codex session on your Mac, and a surface of its own for talking to your agents by text, dictation or voice.

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:

| Mark | Meaning |
| - | - |
| Animated indicator, shimmering title | Working now. The indicator is three dots unless you choose another in [Settings > Sessions](https://docs.agenium.io/app/settings.md#sessions). |
| Raised hand and a **Needs input** tag | Waiting for your answer. |
| A second animated indicator and a **Watching** tag | A Claude session whose turn ended but which has armed something that wakes it by itself: a monitor, a background command, a background subagent, or a scheduled wakeup. The tag's hover hint names what it waits on. |
| Still accent dot, title in semibold | Unread: the agent wrote after your last turn and you have not marked it read. |
| Nothing | Idle or ended, and read. |

Under Reduce Motion the indicators stand still.

### Order

Choose the order in [Settings > Sessions](https://docs.agenium.io/app/settings.md#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.

### Filters and search

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](https://docs.agenium.io/app/settings.md#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 Agenium'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 Agenium.

## 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 Agenium 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 Agenium runs, an agent can answer with Agenium'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](https://docs.agenium.io/app/agents.md#secrets). The value never enters the conversation; the agent learns only that it was saved.

## Talk to a session

Agenium 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.

Agenium 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. Agenium 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](https://docs.agenium.io/app/settings.md#claude-and-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](https://docs.agenium.io/app/settings.md#transcription). macOS asks for the microphone on the first press.

### Voice mode

With voice mode on in [Settings > Voice](https://docs.agenium.io/app/settings.md#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](https://docs.agenium.io/recipes/talk-to-an-agent-by-voice.md).

## Where a session runs

A session runs on one of its agent's [nodes](https://docs.agenium.io/app/agents.md#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 Agenium runs continue by themselves after Agenium restarts. At launch Agenium sends each one that was working, watching or waiting on something it armed a short phrase saying Agenium 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.