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

# Agent sessions

> Create, watch, pause, fork, and resume Vibex Agent sessions.

A session stores the input, Agent output, and tool activity of one development task as a structured timeline. The **authoritative runtime** holds the authoritative timeline; other clients only display its projection.

## Create a session

1. Choose the target project and location (**Local** or **New Worktree** — see [Projects and workspaces](/docs/en/workspaces)).
2. At the top of Composer, choose the Agent, provider profile, model, **Thinking depth**, and **Conversation mode**.
3. Enter your task. Use `/` to pick a command, `@` to reference a workspace file, `$` to insert a Skill, or `↑` / `↓` to recall an earlier message from this session; you can also add an attachment.
4. Confirm the workspace and permission scope before sending. The Agent may need to read files, run terminal commands, or request extra authorization.

Switching Agent or model only affects later runs. Messages already written to the timeline keep their original run identity.

## Reading the timeline

| Item                     | What you see                                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| User and Agent messages  | Markdown text and attachments.                                                                                       |
| Reasoning                | A summary of the Agent's reasoning, which you expand or collapse with **Expand reasoning** / **Collapse reasoning**. |
| Plan                     | Pending steps and their progress.                                                                                    |
| Tool and process details | Tool names, argument summaries, processes and exit results, and the **{n} process events** count.                    |
| Permission requests      | Operations waiting for you to approve or deny.                                                                       |
| Elicitation forms        | Typed forms the Agent needs you to fill in.                                                                          |
| Delegation               | The state and result of child Agents or delegated tasks.                                                             |
| Status events            | Running, queued, waiting, completed, failed, stopped, and reconnecting.                                              |

The elapsed time above a turn is shown as **Worked for**. While output is being generated you see **Thinking...** or **Waiting for confirmation...**.

Tool arguments, terminal output, and file diffs can contain sensitive content. Review and redact them before sharing diagnostics.

## Goals

Agents that support goals publish their state over ACP: the provider-neutral `_meta.goal` extension and Codex's legacy `_meta.codex.goal` namespace. Vibex normalizes both into one shared model and saves every change as a goal timeline item.

The goal lives in a fixed bar above the composer, stacked directly under the queued-message bar:

* The bar shows the phase, the objective, and the provider's own stats (time used, token usage, rounds).
* The pencil button (**Edit goal**) opens an inline editor; saving issues a goal control instead of going through the composer.
* **Pause goal** / **Resume goal** pause or resume the goal.
* **Clear goal** clears it; active, paused, blocked, and usage-limited goals can all be cleared.

Each control appears only when the adapter advertises it. A message sent with `/goal` keeps its own bubble and wears a goal icon on the bubble edge.

## Controlling a run

| Action                    | Description                                                                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Stop current response** | Stops the current run. Files already written or commands already executed are **not** rolled back automatically.                                |
| **Continue**              | Keep sending tasks in the same session.                                                                                                         |
| **Retry**                 | Re-run a failed turn according to the retry semantics the Agent supports; for external operations you are unsure about, check the result first. |
| **Fork**                  | Create a branch session from the current timeline — handy for comparing two implementations.                                                    |
| **Rename**                | Change the session title. It does not change the Agent context.                                                                                 |
| **Edit message**          | Rewrite the last user message; timeline events that already completed are not rewritten.                                                        |

<Warning>
  Stopping an Agent only stops the run. It does not undo file, Git, or external service changes. Check the result in the Git diff and in the terminal.
</Warning>

## Message queue and auto-continue

Follow-up messages you send while a run is active go into a queue. The queue area above Composer gives you:

* **Auto send** / **Manual send** — switch between automatic and manual submission of the queue.
* **Steer** — appears only for Agents that negotiated native steering: it injects this message into the running turn instead of interrupting it first. Every other Agent still falls back to interrupt-and-resend.
* **Send queued message**, **Edit queued message**, **Delete queued message** — act on one item at a time.
* **Resume queued messages** / **Clear queued messages** — resume or clear the whole queue.

How a queued message was delivered is recorded on the user's message and rendered as a reaction on the bubble edge: **Steered into the running turn** (primary) or **Interrupted the turn and resent** (warning). Once a later turn exists, the earlier turn is marked superseded: its live status, running duration, and streamed-row extension stop, while the rows it already produced stay visible and expanded.

Canceling or deleting a queue item does not undo work that already completed.

With **Auto-continue** enabled, only turns allowed by the session settings and the Agent's capabilities advance on their own. The run stops and waits when it hits a permission request, an elicitation form, a failure, or a choice that needs you.

## Permission requests and elicitation forms

When an Agent asks for a terminal, a file write, or another protected capability, the timeline shows the reason and the scope of the request, usually including the working directory, arguments, and environment variables. Your options are **Approve**, **Deny**, and **Always allow for session**.

Elicitation forms ask for structured input. Check the values and the scope before you submit; canceling a form returns a cancellation result to the Agent rather than an implicit approval.

## Global search

`cmd-k` opens the workbench command palette (**Global search**) from anywhere; the entry point is the search icon in the title bar, immediately before the runtime control. One query answers over three groups:

| Group                              | Scope                                    | Selecting a row                                                                                |
| ---------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Recent sessions** / **Sessions** | Session titles and message bodies        | Opens the session and jumps to the message that hit                                            |
| **Settings**                       | Settings entries                         | Opens Settings on the matching section with the row highlighted                                |
| **Quick actions**                  | Real actions registered on the workbench | Runs it; each row shows its keybinding, and unmet preconditions are disabled rather than inert |

* The palette draws its own query field at the top and rules between the three groups; an empty query lists only **Recent sessions**.
* Session search indexes and highlights conversation text only — user messages, agent answers, reasoning, and plans — and tints just the matched keyword, with the current match painted stronger.
* With a non-empty query, `escape` clears it on the first press and dismisses on the second.
* The index is built in the background and kept, so reopening the palette is instant. Archived sessions are not searched.

Finding something inside one session still uses `cmd-f` (**Find in conversation**).

## Importing local history

Import another Agent's history from the **More** menu in the sidebar or **Import sessions** in a project's context menu.

Fourteen sources are supported: **Claude Code**, **Codex**, **OpenCode**, **Gemini CLI**, **Cline**, **Hermes**, **CodeBuddy Code**, **Kimi Code**, **Pi**, **Grok**, **Cursor**, **DeepSeek Harness**, **ZCode**, **Google Antigravity**.

The flow:

1. Vibex scans local history and shows **Scanning local Agent sessions...**.
2. In the preview list, tick the sessions you want, grouped by project. You can filter by Agent or scan again.
3. Click **Import {n} sessions** and wait for **Import complete**.

Results fall into four groups: **Imported**, **Already imported**, **Not found**, and **Failed**.

<Note>
  The scanner reads metadata only: title, time, workspace path, message count, and source path. Content is re-read at import time and written to the timeline in one pass. Credentials, keys, and the full Agent home configuration are **not** imported. Sessions you already imported are never imported twice and are never overwritten by a refresh.
</Note>

## Notifications and unread

The authoritative runtime can send desktop notifications when a session completes, fails, or waits for input. The three notification types can be toggled separately under **Settings → Session → Agent notifications**; they moved there from **General**.

Sessions with unread completions show a dot in the sidebar; opening the session clears the dot, and the authoritative timeline is the source of truth. The system tray menu also offers shortcuts to **New chat**, **Config Center**, and **Settings**.

## Child Agent timelines

When a session uses delegation, a **Child Agent timelines** entry appears in the right sidebar. From there you can open a child Agent's own timeline and jump to it from the parent session.