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, New Worktree, or Temporary session—see Projects and workspaces).
2. At the top of the composer, choose the Agent, provider profile, model, Thinking depth, Conversation mode, and the built-in tools available to this session.
3. Enter your task. Use / to pick a command or Prompt, @ to reference a workspace file or an Agent, $ to insert a Skill, or ↑ / ↓ to recall an earlier message from this session; you can also add attachments.
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

A turn shows its Worked for duration. While generating it shows Thinking… or Waiting for confirmation…. Settled turns fold; the transcript reads a bounded window and paging older history does not move your place. Tool arguments, terminal output, and file diffs may contain sensitive content. Review and redact before sharing diagnostics.

​

Session groups and split panes

A session group collects several sessions under one worktree, useful for several Agents or branches of one task:

• Multi-select sessions in the sidebar and choose New session group.
• Split pane to view members side by side, or Merge panes to return to one view.
• The group header shows team state: running, waiting for approval, completed, or failed.
• Auto continue can be enabled for the whole group.
• Drag a group into a folder, swap it with another group, or drag it back to the workspace root; drag a member within the group to reorder, or out to remove it.
• Dissolve session group does not delete the sessions.

A group can only contain sessions from one worktree. Use several groups for several worktrees.

​

Goals

Agents that support goals publish them over ACP: the generic _meta.goal extension and Codex’s older _meta.codex.goal namespace. Vibex normalizes both into one model and stores every change as a goal timeline entry. The goal bar sits above the composer, directly below the queue:

• It shows the phase, the goal, and the Agent’s own statistics (elapsed time, token usage, turn count).
• The pencil button (Edit goal) opens an in-place editor; saving goes through goal control, not the composer.
• Pause goal / Resume goal pause or resume it.
• Clear goal clears it; running, paused, blocked, and quota-limited goals can all be cleared.

Buttons appear only when the adapter explicitly declares support. A /goal message keeps its own bubble with a goal icon at the edge.

​

Delegation and Agent teams

A delegated task has a lifecycle:

• Keep open: the child session survives after the round and accepts follow-ups.
• Accept: confirm the result; a retry resolves to the original acceptance instead of overwriting earlier work.
• Cancel: permanent; it blocks new messages and new child work anywhere under the task.
• Follow up: only a task that actually ran can be followed up; a changed intent is refused.

The UI shows:

• The sidebar ownership tree: child sessions hang under the parent with a tree guide.
• The session group’s team status header: how many child Agents are running, waiting, or done.
• A delegation card that locates the child pane.
• The @ menu split into Files and Agent delegation tabs, each row saying what it names.

A child Agent has its own timeline, reachable from Child Agent timeline in the right rail. A child’s generated title never replaces the root session title.

​

Control a run

​

Queue, steering, and scheduled sends

Messages sent while a turn is running go into the queue. The queue area above the composer offers:

• Automatic / Manual sending.
• Steer: only for Agents that declare native steering; it injects the message into the running turn instead of interrupting. Other Agents fall back to interrupt and resend.
• Schedule send: pick an hour and the message waits in the queue; the schedule survives restarts, can be edited in a popover, and is visible to other clients.
• Send queued message, Edit queued message, Delete queued message.
• Resume queue / Clear queue.

The delivery mode is recorded on the user message and rendered as a reaction at the bottom of the bubble: Steered the running turn (primary) or Interrupted the previous turn and resent (warning). When a newer turn exists, the older one is marked superseded: live state, duration, and streaming expansion stop, but rows already produced stay visible and expanded. Deleting or cancelling a queue item does not undo work already done. A scheduled send still respects session state and permissions; if the session is waiting for approval, the send waits rather than skipping it.

​

Auto-continue

With Auto-continue on, only turns that satisfy session settings and Agent capabilities advance automatically. It stops at permission requests, elicitation forms, failures, or choices that need a human.

• It is on by default and can be changed under Settings → Session.
• A session group can enable it for the whole group.
• During the countdown, cancel the current continuation from the UI or with t in the TUI.
• Auto-continue never bypasses permission approval or answers an elicitation for you.

​

Permission requests and elicitation

When an Agent requests the terminal, a file write, browser navigation, computer use, or another protected capability, the timeline shows the reason and scope—working directory, arguments, environment. The choices are Allow, Deny, and Always allow for this session. An elicitation form asks for structured input. Confirm values and scope before submitting; cancelling returns a cancellation to the Agent, not an implicit approval. A computer-use approval card also names the target application, action class, and reason; destructive or foreground actions carry a screenshot. Password managers, secure fields, and Vibex’s own windows are handled per action or hard-denied.

​

Global search and find

cmd-k opens Global search (the workbench command palette) anywhere; the entry point is the search icon in the title bar, just before the runtime control. One query searches three groups:

• The panel has its own query field and separators between groups; an empty query lists Recent sessions.
• Session search indexes and highlights conversation text only—user messages, Agent replies, reasoning, and plans—and colors only the matched keywords, with the current hit stronger.
• With a non-empty query, escape clears it first, then closes on the next press.
• The index builds in the background and stays warm; archived sessions are not searched.

Use cmd-f for Find in current session.

​

Import local history

Use Import sessions from the sidebar’s More menu or 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, and Google Antigravity.

1. Vibex scans local history and shows Scanning local Agent sessions….
2. Select sessions in the preview, grouped by project; filter by Agent or rescan.
3. Click Import sessions and wait for Import complete.

Results are grouped into Imported, Gone, Failed, and similar states.

​

Notifications and unread state

When a session completes, fails, or needs input, the authoritative runtime can send a desktop notification. The three kinds can be toggled separately under Settings → Session → Agent notifications. A session with an unread completion shows a dot in the sidebar; opening it clears the dot and the authoritative timeline wins. The tray menu also offers New session, Config Center, and Settings.

​

Archive and restore

Archiving keeps the full timeline and only removes the session from the sidebar:

• Archive from a session row menu, the multi-select menu, or the bulk bar; it is reversible, so no confirmation appears.
• Settings → Archived sessions restores or permanently deletes.
• Automatic archiving can be set per project/folder to an idle window (off, or 1–14 days).
• A mistaken archive can be undone; a delete cannot.

​

Child Agent timelines

When a session delegates, the right rail shows a Child Agent timeline entry. A child has its own timeline, and its updates are attributed so they never fold into the parent’s rows.

​

Continue in the terminal

The Vibex TUI attaches to the same runtime and reads the same sessions, sends messages, handles approvals, and manages the queue. vibex opens the new-session page for the current directory; Ctrl+L opens the session list. See Vibex TUI.