VibeX’s object model and UI follow a small set of stable rules. They apply across agents, conversations, workspaces, and remote connections.

Many agents, one pipeline

Claude Code, Codex, OpenCode, and other registry agents share install, probe, authentication, and new-session paths. Switching agents switches the identity in the list. The application binary stays the same. Each agent’s login, keys, model catalog, and native plugins stay in that agent’s official directory. Claude Code’s config authority is ~/.claude. VibeX reads that directory, starts profile-declared official actions, and attaches the ACP session to one timeline. See ACP and the native agent.

Conversations, delegation mentions, and permission records use a stable agent kind (claude_code, codex). Display names can be localized. The kind stays.

One in-flight turn per conversation

A conversation runs at most one turn at a time. Parallelism is multiple conversations. When uncommitted files must stay isolated, bind each conversation to a different worktree.

Merge, push, and publish happen in the Git panel. Approving a file write releases that one tool call. Commit and push are later steps.

Scheduling and landing are separate

Kanban shows many conversations and schedules work. Workspace shows files, Git, terminal, and browser for the bound tree. The two layouts are saved separately under Settings → Appearance. Dragging a conversation panel changes placement. Kanban still schedules; Workspace still lands.

One Host, one set of facts

Projects, conversation events, plugin activation generations, and automation runs take the current Host data directory as authority. Desktop, WebUI, workstation, and companion read the same objects through Application Core. Every client reads the Host event log. The turn state machine lives in Core. See One Host and Application Core.

Honest capabilities

Session auxiliaries (usage, plan, goals, compaction, draft, find) render facts the agent or the user actually supplied. Missing stays missing. Unknown stays empty. Only capabilities the agent declared appear as controls. ACP capability bits, built-in profile declarations, and plugin enablement jointly decide which entries appear.

A Host is VibeX’s execution plane: the process that owns one data directory and serves the remote protocol. Agent processes, worktrees, plugin workers, the automation engine, official MCP, and chat-channel adapters run on that Host.

Who can be the Host

Opening the desktop app on this machine makes that process the Local Host. For a long-lived process, a machine without a GUI, or browser access on a LAN, run vibex-server. Server shares the data directory, agents, conversations, automations, and plugins with desktop. Server has no Tauri window. WebUI ships as web/ in the distro; a browser opens the address the Host publishes.

One data directory is occupied by one Host at a time. If vibex-server already holds the directory, this machine’s desktop attaches as a workstation. That constraint keeps a single scheduler for the automation engine, conversation events, and plugin workers.

Data directory and native config

Projects, conversation events, plugin installs and activation generations, automation specs and run history live in the Host data directory. Each agent’s official config stays in its own directory, for example Claude Code in ~/.claude. The Host reads those directories and offers official login and declared fields in Settings. The Agent Runtime remains the authority for native files.

Where remote work executes

Remote edits, terminals, and plugin workers act on files and processes on the Host machine. Paths the client shows belong to the Host. The embedded browser and Office preview also run on the Host. Remote clients use them through capability negotiation and the preview proxy.

Clients identify a machine by Host identity. A URL is only a reachability origin. See Remote connection model.

Single scheduler

The automation engine lease, conversation event append, plugin activation-generation switch, and chat-channel inbound all require one scheduler at a time. Two desktops, or desktop plus Server, claiming the same data directory would duplicate due claims and sequence numbers. Occupancy check either demotes the second process to a client or refuses Host start.

The Host console and paired-device presets are separate: operations stay on the machine running the Host; a workstation receives the coding loop.

Application Core is the product’s use-case façade. Opening a conversation, handling permissions, editing files, running automations, and starting or stopping plugins are defined here. Desktop Tauri commands, Web routes, and the remote-desktop adapter only authenticate, map DTOs and errors, then call the same Core. The frontend reaches features through Core via the transport.

Transport

The React UI reaches capabilities through BackendTransport. A local window uses TauriTransport. Browser WebUI and a remote workstation use WebTransport. Transport owns the auth envelope, DTOs, and error codes. Business rules stay in Core.

A permission answered on desktop is the same event in WebUI. Queued input and drafts live on the Host conversation. Authorized devices continue editing them. Every client shares one turn state machine. See Input control.

Capability negotiation

Clients negotiate capabilities over the remote protocol. A built-in browser that exists on desktop may be absent in WebUI. Missing capabilities hide in the UI or fail closed on invoke. Desktop and Server must belong to the same version family. A companion may be one minor version behind and still negotiates. A version or capability mismatch fails the connection.

Window and Host

One application window binds one Server Profile, which is one Host identity. Projects, conversations, agents, and settings in that window all come from that Host. Another Host needs another window. See Remote connection model.

Remote protocol

remote-protocol supplies versioned stable IDs, an error envelope, capabilities, typed commands, and durable subscription DTOs. Durable attach treats Conversation sequence as authority: ready → snapshot or replay → high-water → live. Sequence deduplicates. Unknown event kinds may be kept or ignored.

Application Core methods are the public seam for desktop commands, Web routes, and the Remote Desktop adapter. Adapters must not copy a second turn state machine or plugin control plane locally.

One product version produces one Host family with aligned semver. Desktop, the vibex-server directory, and official plugin snapshots come from the same build. A client and a Host must belong to the same version family to pair.

Artifacts

The family artifacts are desktop, Server directory, and companion. Chat-channel adapters run with the Host. Chat-channel adapters run with the Host.

Daily shapes

Everyday use is the desktop app; that process is the Host. For a long-lived process, a headless machine, or LAN browser access, use Server. The unpacked Server directory is:

vibex-server
vibex-mcp
web/
plugins/bundled/

WebUI is web/. A local browser opens the Web UI address from Settings → Remote connection. The desktop default listen port is 17891, subject to current config. Agents, Git, and the terminal still execute on the machine running Server or the desktop Host.

A companion may be one minor version behind. Packages are on GitHub Releases. Install steps are in the desktop guide and Server guide.

Every agent follows the same path before a new conversation: probe the local runtime, confirm identity, then evaluate authentication and enablement. Built-in agents and registry-added agents use this pipeline. Source only changes where the profile comes from. Install, probe, and new-session semantics stay.

Sources

There are three sources.

Built-in agents are pre-added and carry an official profile: run topology, detection rules, login actions, native config paths. The current set is Claude Code, Codex, DeepSeek Harness, Pi, OpenCode, Gemini CLI, Cursor, Grok, OpenClaw, Hermes, Kimi CLI, CodeBuddy, and Cline. A profile may declare official account, subscription, Provider, and native plugin management. Pipeline steps stay aligned.

The official ACP registry discovers and adds other coding agents. After add, install, probe, and conversation still use this pipeline. Entry count follows the in-product registry for that build. If upstream removes an entry, an already-added agent keeps its stable identity.

Manual registration accepts only registry-compatible distributions: Binary, npx, uvx. Registration stores a stable agent id, distribution, and definition digest, then reuses the same installation lock and launch gate. A same-named program on PATH joins the list only through the add flow.

Identity

The Settings agent list is the added set. The last slot opens the registry. Each agent has a stable kind, for example claude_code or codex. Conversations, delegation mentions, permission records, and automation targets use kind. Display names may be localized.

A registry id identifies a registry entry. Kind is a different object. VibeX aligns them with an explicit binding, not by similar names.

Installation lock and launch gate

After a successful probe or user-environment install, the Host records an Installation lock: runtime path, ACP adapter path, version, and distribution. The lock makes the current binding verifiable and rollback-capable. CLIs live in the user environment (PATH, npm global prefix, uv tools, user bin). Platform install writes into that environment as well.

On new session, the launch gate checks that lock, the chosen authentication mode, and required profile dependencies. Subscription mode clears inherited-process keys that conflict with that mode. See Install, authenticate, enable.

Handoff into a conversation

The list, locks, and enablement come from Settings → Agents. The Coding agent picker on Create session reads enabled, ready rows. Kind is written into later events for that conversation. Delegation mentions & also resolve by kind. Renaming the display label or switching UI language leaves existing conversations on the same kind.

VibeX talks to an agent over ACP (Agent Client Protocol). Handshake, capability negotiation, session create, turn prompts, and permission requests use that protocol. VibeX is the client on this link. The Agent Runtime is the server.

Login, keys, model catalogs, and native plugins stay in that agent’s official directory. Claude Code uses ~/.claude. Codex uses its own auth.json and config.toml. VibeX may start profile-declared official login, or write fields the profile already names. Native config files remain the Runtime’s persistent authority.

Authority

When ACP and a local probe can both supply the same status, ACP wins. A built-in profile may offer a local management fallback only when ACP lacks that status. Ordinary registry entries have no dedicated local probe.

Credentials

Auth credentials are held by Agent Runtime config or the user’s external environment. VibeX may start the official account flow, or edit locally declared credential fields. Terminal interaction is not harvested into a second secret store. In-page device authentication exists only for adapted, fixed-endpoint official flows (currently Codex): a short-lived device code may cross IPC; the access token is exchanged in the backend and written straight into the official credential file.

Topology

Local agents split by install shape into native ACP and adapter-backed ACP. See Native ACP and adapter ACP.

Native plugin management

Settings → Agents → the agent’s detail can fold out a native plugin list. It only shows Skill, MCP, Runtime, Hook, and Workflow owned by that agent. Actions depend on a reliable native adapter. VibeX App extension rights stay with VibeX plugin packages.

A local agent has two run topologies. The topology is written in the agent profile. Install and preflight check different parts accordingly.

Native ACP

The installable itself speaks ACP. After install and a passing probe, a conversation can start. Most registry entries ship this way. There is one runtime component to install and verify.

Adapter-backed ACP

The ACP process only bridges. Actual capability comes from another local Runtime. Both parts must be installed and bound explicitly. The built-in profile names topology and detection candidates. The adapter must use the CLI the profile declared. If Runtime or the bridge is missing, preflight fails. An ACP process that is already up still needs a valid Runtime binding before a conversation can be created.

Launch constraints

This pipeline starts ACP on local stdio only. Registration must yield a reviewable local install. A remote ACP address, HTTP or WebSocket endpoint, user-defined launch command, and download-and-run on every start sit outside this pipeline.

If a registry entry depends on an undeclared external program, preflight fails and the entry is marked unsupported. Undeclared-dependency entries stay marked unsupported.

When the current OS or CPU has no distribution contract, the agent is marked platform-unsupported. Existing identity and membership stay.

User-environment install

Runtime and ACP live in the user environment: PATH, npm global prefix, uv tools, user bin. Platform-provided install writes there, then probe follows PATH. The Installation lock records that observation. CLIs live in the user environment. The Installation lock records that observation.

A new conversation requires three states at once. The three states are independent. Each state is stored on its own.

The list may show rows that are not ready, marked needs authentication, needs configuration, or needs repair. Creating a session requires installed, authenticated, and enabled.

Probe

The desktop app probes built-in agents once at first launch. A probe is a one-shot observation with a timestamp. A successful probe only means the local runtime is visible. Login and Enable are completed separately in Settings → Agents.

Management-degraded means core run and required auth are healthy, while an optional management capability failed to probe. The row can still open a session.

Uninstall and remove

Uninstall removes the CLI from the user environment by distribution and clears the installation lock. Added membership, settings, and history stay, so the agent can be installed again. Node, npm, uv, and agent-native config remain.

Remove drops a non-built-in agent from the list: uninstall first, then clear VibeX-owned agent settings. History stays. Built-in agents always remain in the list. They may be disabled or unauthenticated.

A retired agent stops add, install, and new sessions. The stable identity remains so history stays interpretable.

How-to steps: Enable and authenticate and Add an agent.

A Host is the process that currently owns a VibeX data directory and serves the remote protocol to clients. Its shape is the desktop app or vibex-server.

Identity and profile

Host identity is shown in pairing and capability negotiation. It is the key clients use to merge a Server Profile. URL, LAN IP, and tunnel hostname are reachability origins and change with the network. Identity stays. The Host console is the default Local Profile. A remote profile stores non-secret metadata and multiple reachability origins. Access credentials are protected separately.

Host console

The machine running the Host exposes the console: listen port, reachability publish, pairing invitation, device list, admin token, backup/restore, and upgrade. The console belongs to that Host process. A remote workstation uses conversations, files, Git, and plugins. Operations stay on the console.

Single occupancy

One data directory is occupied by one Host at a time. If desktop already holds it, Server attaches or waits. Host start is reserved for the occupant. If Server already holds it, this machine’s desktop attaches as a client. The automation engine, conversation append, and plugin workers therefore have one scheduler.

Native config boundary

Projects, conversations, plugin activation generations, and automations live in the data directory. Each agent’s official config stays in its own directory. The Host probes, projects, and starts official actions. The Runtime reads and writes its own files.

Host family

Desktop, the vibex-server directory (vibex-mcp, web/, official plugin snapshots), and the companion package from the same product version form a Host family. Pairing and capability negotiation align on family version. See Desktop, Server, and WebUI.

The remote model separates “which Host this is” from “which network path reaches it right now”. Clients identify a Host by Host identity. When LAN, Tailscale, or a reverse-proxy name changes, the profile still names the same machine.

Pairing invitation

The Host console presents a pairing invitation that includes:

• Host identity
• Device permission preset (workstation or companion)
• Currently available reachability origins (loopback omitted)
• A secret that lasts about five minutes and can be redeemed once

Long-lived device credentials go in the system keychain or Android Keystore. The invitation, QR, and URL carry only the one-time secret. An unpaired device redeems the secret for a durable credential. A device that already paired only merges reachability when it scans again. After the secret expires, a newly presented invitation can still supply origins. Browser WebUI uses workstation pairing.

A pairing relation is one client identity under the same Server owner. P0/P1 treat devices as that owner’s clients. Team members and multi-tenant isolation are out of this model. Disconnect, app restart, network change, or admin-token rotation leave the pairing in place.

Server-bound window

One application window binds one Server Profile. Projects, conversations, agents, and settings in that window all come from that Host. Another profile uses another window.

The remote coding loop covers: pick project and workspace, run an agent, handle permissions, edit files, review diffs, Git, and terminal. Desktop-only operations (Host console) hide when the capability bit is absent.

Disconnect, forget, revoke

Disconnect closes the current network link and keeps profile, cache, credentials, and pairing. Closing the window, quitting the app, and a network drop are disconnect.

Forget server deletes the local profile, read-only cache, and system credentials. When the Host is reachable, the client first asks to revoke this device.

Revoke device ends that device’s long-term trust on the Host. Existing connections and later requests fail immediately. Main token and device token are forbidden in URLs, events, and logs. Admin-token rotation keeps paired devices.

Related terms

• Server owner: the single principal with final authority over one data directory and its paired devices.
• Server profile: the client’s local identity for one Host, keyed by Host identity.
• Reachability: one origin that finds the same Host.
• Paired device: a client identity holding a long-lived, revocable device credential. Device and User are different objects.
• Durable attach: the subscription contract keyed by conversation sequence.

Reachability names the network path a client uses to reach a Host. One Server Profile can record LAN, FRP, Tailscale, or Cloudflare origins at once. The remote protocol and the workstation or companion preset stay the same across origins.

Bind and publish

Loopback is the default bind. A local browser uses the Web UI origin on loopback. 127.0.0.1 is omitted from pairing invitations. A phone needs a LAN or published origin.

LAN access requires Allow LAN in Settings → Remote connection. Public access should terminate TLS on a reverse proxy, then forward to the Host. Cross-origin entries in the allow list are exact browser Origins.

Tailscale, FRP, and Cloudflare tunnels are deployed by the operator. VibeX writes a remote address to the authoritative list after it passes the check. A failed check or unpublished origin leaves the list. LAN addresses come from probe.

Client attempt order

Clients try last-success, remote HTTPS, then remaining items. The Host refreshes the list while online. After a network change, a paired device reuses the same credential on a new origin. The existing credential is reused.

Every origin ends on the same Remote Protocol: versioned commands, error envelope, capability bits, and durable subscriptions. Permission range per connection is in Four connections.

Relation to pairing

Reachability is a list on the Server Profile. A paired device is a durable credential. Changing Wi-Fi or a reverse-proxy name updates reachability. The permission preset chosen at pairing stays.

Besides this machine’s desktop acting as Host, four ways attach to that Host. Pairing chooses a device permission preset. The preset presents a bundle. Authorization still uses fine-grained scopes.

Workstation

A workstation is a near-full remote desktop client. The CEF browser and Office preview run on the Host. Remote access uses capability bits and the preview proxy. Plugin management changes activation generations on the Host.

Companion

The first companion platform is Android. While the Host is offline, the app reads the offline conversation cache. That cache holds durable sequence and open events with read_only true. No write is queued during a network drop.

Chat channels

Feishu, Weixin, QQ, and Telegram adapters run on the Host. Those IM apps remain vendor clients. An empty authorized-sender list closes inbound. An approval on a channel resolves the same pending request as desktop. Terminal notification summaries carry stable IDs, terminal state, and time. Prompt, output, and file paths stay out of the summary.

How-to: Connect to a Host, Phone companion, and Message channels.

Preset and scope

Workstation and companion are presets shown at pairing. Actual allow/deny uses scopes. Server administration stays on the Host console. WebUI uses workstation pairing. Chat channels use the authorized-sender list, separate from the paired-device table.

A conversation is a durable dialogue between a person and one agent. The full history lives in an append-only event log. Timeline messages, tool calls, permission requests, and error cards are projections folded from that log. If the log exists, the conversation exists. A projection can be dropped and rebuilt. It is not the authority.

Relation to the process

When the agent process exits, the window closes, or a panel moves to another group, the conversation remains. Resume loads context into a newly started agent process. See Turn state machine.

Inside one window, a conversation maps to at most one panel. Opening it again focuses the existing panel. Closing or moving a panel only changes layout. An in-flight turn continues. The conversation record stays. See Conversation panel.

One log, many clients

Other windows, the companion, and WebUI can view the same conversation, keyed by event sequence on the Host. Durable subscribe uses snapshot, replay, and live against that sequence. Clients read the Host log. Unknown event kinds must be keepable or ignorable so an old client can skip a new event kind.

Panel layout is stored on the client, isolated by Host, project, and window. Drafts belong to the conversation on the Server. Authorized devices continue editing them. See Input control.

Belonging

A regular development conversation binds one workspace. A workspace-less conversation can also be created. Turn rules, resume, and interrupt semantics match. The latter has no Git panel and no repository tree.

Two independent conversations may have a parent-child relation for navigation and rollup. Each conversation keeps its own log. The relation is used for navigation and rollup. A delegated child is this kind of relation. See Delegation.

Auxiliaries

Usage, plan, goals, and compaction render facts the agent or the user supplied. Find locates text in the current timeline. The child list shows rollup on the relation; opening a child enters its own panel.

Events and projection

The log is append-only. Projection folds events into timeline rows. Each row has a monotonic revision for incremental, idempotent updates. A snapshot is a materialised cache at some sequence and can be discarded. The frontend’s only render input is timeline rows.

A turn is one full cycle from the user sending to the agent finishing a reply. A conversation has at most one in-flight turn. Parallelism is multiple conversations.

Terminal states

When a turn ends it enters exactly one of the following. The states are exclusive.

Interrupted means the Host process disappeared. The agent may already have written files. Startup recovery marks leftover in-flight turns Interrupted so the conversation can accept a new turn. An interrupted turn is started again by the user.

Resume and rebind

Resume loads context into a newly started agent process. The in-progress token stream ends with the old process. Whether resume is available depends on capability bits the agent declared over ACP.

When loading the old agent session fails, confirmation may attach a new cold-start session (rebind). VibeX history stays. Hidden agent-side context starts empty. Handoff for the new process is written in the next message.

Fork

When the agent declares fork and an active session exists, fork copies visible history and agent-side context, then evolves independently. Otherwise the new conversation is a copy without hidden context. Fork starts from the current state.

Rollback to here on a user message truncates later generation so the user can edit and resend. Undo under a turn restores workspace files to the checkpoint taken before that message. The conversation record stays.

How-to: Turns: stop, resume, fork.

One in-flight at a time

While idle, the scheduler claims the next queued input and makes a new turn. Sends during an in-flight turn join the queue. Steering writes into the current in-flight turn. Cancel applies to that turn. Content already in the event log and files already written remain.

Handoff from orchestration

Delegated children, Workflow agent steps, and Automation single-session targets all create real turns. They reuse this chapter’s terminal states and the one-in-flight rule. Workflow pause cancels in-flight turns and continue opens a new turn. Automation recovery marks leftover direct turns Interrupted.

Conversation input splits into draft, queued input, steering, and permission response. Desktop, WebUI, companion, chat channels, and workflows share the same semantics. Authority is the conversation on the Host. Clients align by revision or event sequence.

Draft

A draft is unsubmitted Composer content belonging to that conversation. Authorized devices continue editing it. Each save carries a revision. On conflict the UI keeps the server version and the local version so the user can Keep server or Keep local. A successful turn submit with a matching revision clears the draft.

Queued input

Queued input is content the Host has accepted and not yet claimed into a new turn. While the conversation is idle, the scheduler turns items into turns in stable order. The queue survives refresh, device switch, and reconnect. Rows can be edited, reordered, or deleted.

A send while a turn is in flight joins the queue. A send while idle starts a new turn.

Steering

Steering is extra input on the in-flight turn. It belongs to that turn. Steering stays on the in-flight turn. When the agent declared the capability, the UI shows Steer this turn. When the agent lacks it, the field is hidden. Queued input remains a separate object.

Permission requests

A permission request is a gate inside a turn. File writes, shell, Git, and MCP tools pause on the timeline until Approve or Deny. Approving a write leaves commit and push in the Git panel. Remote and desktop answers resolve the same request, exclusively.

Opening a project folder and the built-in browser are done by the app. When the agent operates a page or clicks for the user, the timeline shows a separate permission request. See Permission prompts.

Consistency across entries

Desktop, WebUI, companion, and authorized chat channels see the same draft revision, the same queued input, and the same pending permission. After one person approves, other entries show the request resolved. Steering appended to a Workflow agent step follows the same turn or steer semantics as an ordinary conversation.

A project is an opened engineering directory. Conversations, workspaces, and the Git panel belong to that project. The project names “which codebase this is”. The workspace names “which tree this conversation reads and writes”.

How it opens

The desktop home offers Select Folder, Create New Project, and Clone Repository. A directory already recognized as a Git repository opens directly. A directory without .git is initialized on open or create. Clone pulls from a URL, then joins the project list.

A directory with .git can use the Git panel, branches, and worktrees. Paths shown on a remote client belong to the Host machine.

Relation to conversations

One project can hold many conversations. Kanban lists them per project. Opening a card switches the Workspace region to the tree bound to that conversation. Several conversations bound to the same root may overwrite one another’s uncommitted files. Isolation binds each conversation to its own worktree. See Conversation and workspace binding.

Deleting a project removes conversations and workspace data under it. Recent projects are stored on the client.

How-to: Open a project.

Paths and Host

A project path is a directory on the Host machine. Absolute paths in WebUI and on a workstation belong to that machine. Clone, create, and Git init also execute on the Host.

In this chapter, workspace means the execution container a conversation lands on: the project root, or a Git worktree cut from that root. The UI region named Workspace is documented in Workspace. The two words coexist in the product. They name different objects.

Project root

The root is the default landing tree. File, terminal, and Git use this tree until isolation is chosen. Several in-flight conversations bound to the root may write the same uncommitted files.

Worktree

A worktree is a Git working tree. Its path differs from the root. Repository objects are the same. Parallel tasks each bind a worktree so implementation and review use different working copies. Creating a worktree requires the project to already be a Git repository.

That conversation’s file tree, terminal, and Git operations point at this tree. A worktree-bound conversation shows Rebase and Rebase back above the execution pane: the former brings the target branch onto the current tree; the latter then merges the current tree back onto the target.

Delete is constrained by retention. Worktrees owned by a running turn or automation run are kept. After the conversation ends, merge, push, or publish finish in the Git panel.

Per-project post-create command, pre-destroy command, and count cap live in Settings → Worktrees. Global workspace directory and branch prefix live in Settings → Version control.

A workspace-less conversation uses a Host-assigned temp directory. See Workspace-less conversation.

Distinct UI senses

Workspace page under Settings → Appearance is the execution-region layout. Existing workspace / New workspace in the Create session dialog are this chapter’s directory or worktree. The Kanban workspace filter also means that tree. Follow the links in this reference for the intended object.

A conversation binds one workspace. Binding is chosen at create: an existing workspace, or a new Git worktree from the target branch. After bind, that conversation’s file tree, terminal, and Git all point at this tree.

Why one-to-one

A turn writes files. If one conversation mapped to two trees, permission requests, diffs, and timeline patches could not land in a single place. So one conversation binds one tree. Parallel work uses multiple conversations, each with its own bind.

Two conversations may bind the same root. Uncommitted files may overwrite each other. Isolation binds one of them to a worktree.

Lifecycle

Binding is set at create. Later the conversation can bind a worktree added afterwards. Follow-up merge and pull request happen in the Git panel. Automation and Workflow runs default to an independent worktree. Push stays a human step.

A workspace-less conversation has no bind of this kind. See Workspace-less conversation.

Choice at create

Existing workspace binds a root or worktree that already exists. New workspace creates a Git worktree from the target branch, then creates the conversation in that tree. A row marked will checkout first switches checkout before bind. A workspace-less conversation skips this step.

A workspace-less conversation belongs to no project. It is used for conceptual discussion or comparing approaches.

Turn rules, event log, resume, interrupt, draft, and queue match a regular conversation. Git panel and repository tree require a project workspace. Kanban lists project engineering tasks. Workspace-less conversations sit outside that list.

Tool root

The agent may still offer file and terminal tools. The tool root is a Host-assigned directory isolated per conversation. Relative paths resolve there. Absolute paths still follow the agent tool’s own resolution. The mode restricts the default tool root to that isolated directory. An OS sandbox is a different mechanism.

Event authority and the turn state machine match a regular conversation. Git panel and repository tree require Workspace membership.

The main UI splits into Kanban and Workspace. The previous chapter’s workspace is a directory or worktree. This chapter’s Workspace is the execution surface. The two senses of “workspace” coexist. They name different objects.

Responsibilities

Kanban shows parallel conversations in To Do, In Progress, To Review, and Done, and it opens session hub and usage stats. Workspace shows files, diff, terminal, and browser for the tree bound to the focused conversation. When implementation and review run together, look at both cards on Kanban, then open the review conversation to read the diff.

Conversation panels can be dragged side by side. The number of groups in a window is capped. Dragging only changes placement. Kanban still schedules. Workspace still lands.

Layout config

The two layouts are saved separately in Settings → Appearance → Page layout. The Kanban page arranges Session list, Session monitor, and Session execution. The Workspace page arranges Sidebar panels, Workspace, Sessions, and Terminal. A zone keeps its size when moved. Splitters on the page still resize widths.

Kanban lists parallel conversations by project and status. Each card is one conversation. Cards show status and jump into the execution pane.

Three pages

The four-column board uses To Do, In Progress, To Review, and Done. Dragging a card changes status. Clicking a card loads that conversation into the execution pane on the right.

Session hub splits the same work into Sessions, Session monitor, and Session execution. The monitor expands up to four live outputs. Usage stats shows token spend by project, conversation, and model, plus official subscription quota for some agents.

The product can surface about five conversation statuses at once. The list filters by workspace and coding agent, and it can archive, fork, and export Markdown / HTML. Delete skips sessions that are still running.

Relation to the event log

In-flight turns, waiting permissions, and Completed / Failed / Cancelled / Interrupted show on the card. The Kanban card, the UI panel, and the Host event log describe the same conversation. Rename happens on the conversation itself. Opening a card switches the Workspace region to the bound tree.

How-to: Board and many conversations.

Monitor and execution

Session monitor watches several outputs at once. After Move to execution area, input, permissions, and steering happen in the execution pane. Monitor itself only observes. The three zones can swap places in Settings → Appearance.

Workspace is the execution region in the UI. It shows the project root or worktree bound to the current conversation. Sidebar, editor, conversation column, and terminal column share the screen. That layout is saved on its own under Settings → Appearance.

Files and preview

The file tree expands from that workspace root. Common text and code can preview or edit. Very large or unknown types may be read-only. Diff is the check after a write is approved and before commit. Timeline patches point at paths on this tree. Uncommitted edits for a worktree-bound conversation stay on that tree.

High-fidelity .docx / .xlsx / .pptx preview comes from the official VibeX Office plugin. Opening those files starts a read-only preview process.

Git, terminal, browser

The Git panel offers stage, commit, branch, stash, and pull request. Merge and push are human steps. The terminal cwd matches this tree. After permission, the agent may operate the built-in browser. New tab can open Browser, Review, Note, or Terminal.

Paths in WebUI belong to the Host machine. Terminal and preview on a remote workstation also execute on the Host. Output returns over the remote protocol.

Relation to the workspace directory

The Workspace UI always points at the tree bound to the focused conversation. Switching cards switches file tree, Git state, and terminal cwd. Two worktrees can exist under one project. The UI shows one of them at a time.

A conversation panel is the Dock view that presents one conversation in a server-bound window. The conversation opens on the right by default. It can be dragged into the editor area, into a tab group, or into a left-right or top-bottom split. The number of conversation groups in a window is capped, matching the editor group cap.

One panel, one conversation

Each panel has its own event subscription, scroll position, draft view, and in-flight turn. Splits stop at the panel. Inside one window a conversation maps to one panel. Opening it again focuses that panel. Closing a panel only changes layout. An in-flight turn continues. The agent session stays. The conversation record stays.

Layout and draft

Layout is stored on the client, isolated by Host, project, and window. Another client machine needs its panels arranged again.

Drafts belong to the conversation on the Server. Authorized desktop, browser, and Android clients continue editing them. Saves carry a revision. Conflict keeps both versions. See Input control.

Fork and export

Fork on the session list creates a new conversation and a new panel. Export as Markdown or HTML reads the current projection. The event log stays. Delete skips rows that are still running.

Multi-agent collaboration in the product splits into delegation and Graph Workflow. Automation only triggers. Split logic belongs to delegation or the graph.

Delegation

Delegation is the parent agent handing work to another agent in the dialogue. The child conversation runs on its own, with its own event log and turns. It fits work that needs a split inside the current message. The capability comes from the built-in Multi-agent plugin. & in the composer is a structured mention. The parent actually creates a child by calling the delegation tool. See Delegation.

Graph Workflow

A Graph Workflow describes step dependencies first, then executes. The source file can enter Git. A published definition version is immutable. It fits a fixed flow that must be reused and versioned. The capability comes from the built-in Workflow Creator plugin. See Graph Workflow.

Automation

An Automation, on manual run or when the schedule fires, starts one ordinary turn, or one published Workflow version. It binds an exact version and an isolation policy. Split logic belongs to delegation or the graph. Automation decides when to start. See Automation.

A one-off review chain uses delegation, for example handing finished code to another agent for review. A flow that repeats weekly is written as a Graph, published, then started on a schedule by Automation.

Choosing

When this message needs another agent to take over, use delegation. When step order is stable, belongs in Git, and must be started repeatedly by Automation, use a Graph. When the only decision is when to start an already chosen target, use Automation.

Delegation is the mechanism by which a parent conversation hands a bounded subtask to another enabled agent. The child is an independent Conversation: its own event log, turns, and permissions. The parent keeps the relation, policy, and a result summary. The parent keeps a summary.

Mention and tool

& in the Composer is a structured mention, for example &Codex. It asks the parent to consider handing work to that agent. After & appears, the parent still creates a child only by calling delegate_to_agent. If the parent never delegates, no started child is shown. If the current parent lacks companion capability, the mention stays a reference.

Child rules

A child task completes once by default: the first turn reaching a terminal state ends it. Parallel delegations should bind different workspaces so each tree stays isolated. After the parent panel closes, child turns already running continue. Cancel happens on the child conversation or the delegation card. Child permission requests still need a person, with the same rules as any conversation.

Max delegation depth, completed-result cache, and sub-agent defaults live in the plugin config.json and apply only to new children started by delegation. Depth is 1–8, default 1.

Plugin boundary

The capability comes from the built-in Multi-agent plugin. It starts disabled and stays in the catalog. Plugin enablement is delegation enablement. While the plugin is off, & is an ordinary character. Mentions appear in conversations created or rebound after enable. How-to: Agent delegation.

Result return

The parent receives a summary and the return payload that was allowed. Completed results cache in memory for the running delegation session and clear when that session ends. A configured MB cap of 0 means no capacity cap. Release still happens when the session ends.

A Graph Workflow describes step order as a dependency graph. Source artifact, published definition, and run instance have separate identities.

Source and publish

The source file (*.vibex-workflow.json) can be edited repeatedly in a workspace and committed to Git. At that point it is the authoring fact. Publish, after validation, produces an immutable definition version. A failed validation produces no new version. A run binds the definition version at start. Later source edits affect the next version only. An Automation that targets a workflow binds that exact version.

Opening the source enters Workflow Studio. A debug run can execute only the selected step, or continue downstream from it. Debug uses an isolated test worktree. A debug breakpoint belongs to that Debug run only.

Steps

An Agent step runs through a child conversation and real turns. Continuing the dialogue creates a new turn. A cancelled turn stays cancelled. An Approval step waits for an authorized principal. Retry creates a new attempt and keeps the old record.

A completion gate decides how a candidate output is accepted. On manual confirm, Studio derives a visible confirm node that opens the agent-step conversation. When continuing may repeat side effects and the system has no contrary proof, the run enters needs review. A person chooses continue or stop.

Run control

A run binds one definition version, a set of inputs, and a workspace. A new run can be derived from a chosen step of an existing run. The original run stays read-only. Upstream results that still match the contract can be reused.

Pause first stops scheduling new steps, then cancels in-flight turns, and enters a resumable paused state. File and external side effects that already happened stay. Continue opens a new turn in the original child conversation. Merge, push, and publish finish in the Git panel.

Controller and worker

A user may authorize a Controller Agent, separate from the worker that executes a step, to inspect node evidence, append input, or accept a candidate output through Workflow MCP. Every control action is auditable. Workflow MCP depends on a running Host. When the Host is unavailable, publish, debug, and run entries close.

An Automation is a versioned trigger config. On manual start or when the schedule fires, it starts one ordinary turn, or one published Workflow version. Target kind is chosen at create. Turn and workflow stay that kind for the lifetime of the row.

Target and isolation

A single-session target creates a real Turn each run. A workflow target binds a published exact version. After the source publishes again, older automations keep the version they already reference.

The default is an independent worktree per run. Sharing the project root is an explicit choice and must pass a clean tree and branch check. Merge, push, or publish during a run still happen in the Git panel.

Spec JSON can be copied. Import resolves project, agent, and workflow references on the current Host and leaves the row disabled until enable is confirmed. The spec omits database identity, secrets, and machine paths.

Engine owner

One data directory has one automation engine owner: the current Host. Only the owner claims due jobs. If the page says another host holds the engine, the view is read-only.

On Host startup, leftover direct-turn runs become Interrupted. Runs already attached to a Workflow run follow that run’s terminal state. The next fire is still schedule or manual. After downtime, at most the most recent missed schedule is backfilled. Finished runs and their independent worktrees are kept 30 days by default, under a per-directory space quota. Running jobs are kept.

Run records

Each fire produces an Automation run. Terminal state follows the durable fact of the matching Turn or Workflow run. The list can run now, open history, and cancel a running row. Unseen failures surface on the row.

A VibeX plugin package is installed, enabled, updated, and uninstalled under one identity. One package may contribute UI, agent, Host, and runtime at once. Install treats it as a product package. There is no prior split into “platform plugin” versus “agent plugin”.

Lifecycle

Discover or import yields a source package. That is not yet execution rights. Install accepts an exact version/digest as the Host’s immutable install. New installs start disabled. Enable is the durable intent to publish contributions. After enable, the Host produces an activation generation: an atomic snapshot of package, grants, Runtime locks, and ready contributions. A candidate generation is invisible until fully validated. A failed update keeps the previous complete generation.

Conversations that already exist keep the tool list from creation. Later new or rebound conversations receive new contributions.

Turning enable off stops new turns from using the package’s contributions. History in the event log stays. A third-party package can be uninstalled: membership, agent bindings, and Skill projections go away. Conversation and automation history remain. Built-in packages stay in the catalog. The switch only enables them.

Trust

Enabling a VibeX plugin package allows it to run workers and UI with the same local rights as the Host. Separate processes exist for lifecycle, hot reload, and crash isolation. Package layout, content index, and validation are in the developer docs.

Agent-native plugins (Codex / Claude Code package formats) are held by that agent’s storage and trust. VibeX may project a read-only view and forward install/enable when the adapter is reliable. Native trust and VibeX enablement are separate authorities.

How-to: Install and enable a Plugin.

Control plane

The plugin control plane is the sole fact source for install, grant, start/stop, update, diagnostics, rollback, and uninstall. It can also read projections of agent-native plugins. Additions and deletions in native directories still follow that agent. External disable or a broken link must be shown as-is.

Identity

Plugin identity is stable Publisher plus Plugin ID. Display name, folder name, and similar contents leave identity unchanged. Packages with the same ID and different publishers keep separate grants and data. A linked development plugin keeps following a user-chosen directory. After the source changes, contributions, grants, and identity must be revalidated. The development directory stays on disk.

Plugin contributions attach by type to different places in the product. Usability is judged per contribution. A Skill inside the package is one contribution among others. Each contribution has its own identity, type, compatibility conditions, and readiness.

Binding and readiness

Enable allows those contributions to be published. Missing runtime, missing binding, or an agent that rejects the contribution leaves it unready. All-agents binding intent projects compatible contributions onto current and future enabled agents that support the capability. Exclusions are stored separately.

A Skill projection is a controlled read-only entry written to the agent-native Skill location. A user Skill of the same name stays. A Plugin Command and an agent-native command may share a display name and remain distinct by source identity.

A remote workstation changes state on the Host. Companion and chat-channel plugin management lives in Settings → Plugins on the Host or a workstation desktop.

Runtime lock

A Runtime requirement is an author declaration. The install lock records the exact version the Host resolved, integrity, and probe evidence. A successful declaration and a spawned process still require a passing probe before ready. A Host-owned Runtime enters reclamation only after references drop to zero.

The Host family ships official product plugins marked VibeX built-in. They start disabled and stay in the catalog. After the runtime is on disk, enable still has to be turned on. Later new or rebound conversations receive injection. The switch lives on the plugin itself.

Delivery

Official MCP ships with the Host family. After the plugin is enabled, the Host injects the matching MCP into later new or rebound agent sessions and trims tools/list per session. Conversations already open keep the tool list from creation.

The four Session Enhance tools can be turned off individually in plugin config. Multi-agent enablement is delegation enablement. Workflow Creator depends on the running Host loopback gateway. Office preview uses the Host-locked officecli Runtime.

Config writes each package’s config.json and applies to later new sessions or new previews.

Relation to Settings

Session tools and the delegation master switch live on those plugins’ Config tabs. Settings → General leaves those switches on the plugin pages. Office preview idle timeout and Workflow Creator’s default completion policy also live in each package config.