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

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

​

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:

• 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 sessions and wait for Import complete.

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

​

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.