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 official 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 official 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 official Multi-agent plugin. Install it from the marketplace. It starts disabled and can be uninstalled. 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. UI, Agent, and Host contributions may share the package.

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. Sources are marketplace snapshot, GitHub snapshot, local archive, or linked development. A Git #tag / #commit, a marketplace install, or a GitHub Release digest pins a snapshot; an unpinned repository is unlocked. 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. When the origin lock is valid and a newer tag or semver appears remotely, Installed shows Update available. The Host watches a linked development directory and republishes a candidate generation when the digest changes.

Agent-side contributions (Skill, managed MCP, Hook) enter conversations created or rebound after enable. UI and Provider contributions appear on enable and vanish on disable. Conversations that already exist keep the tool list from creation.

Turning enable off withdraws UI and Provider entries immediately. New Agent-side turns stop using the package’s contributions. History in the event log stays. An installed package can be uninstalled: membership, agent bindings, and Skill projections go away. Conversation, artifact, and automation history remain. Config stays by default; delete plugin data also drops the Host-managed snapshot, and unreferenced Runtimes are reclaimed. A linked development directory stays on disk.

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.

Official plugins and third-party plugins use the same public SDK and contribution points. A plugin targets Host contribution points; reuse another plugin by copying its source and packaging it under a new identity.

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.

Contribution	Attach point	When it applies
Skill / MCP / Hook	Agent conversation; visible to that agent after Agent binding	New or rebound conversation
Command / toolbar / status / slash / timeline card / settings section	Matching Host chrome slot	On enable
Top-level tab / workspace panel / kanban view / settings page	Central bar, Dockview, Kanban container, settings sidebar	On enable
File opener / preview / editable file tab	Workspace files and artifacts	On enable
Provider import / remote provisioner	Model Provider import menu; provision of a saved Host	On enable
Workflow	Orchestration; publish path matches the source file in the repo	Available after enable
Host Worker	Host background; clients observe a projection	With the activation generation
Runtime	Exact CLI / Binary / sidecar version, resolved and locked by the Host	Ready after a passing probe

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.

Several plugins may occupy the same slot. The Host aggregates what can be aggregated (status items, side-by-side panels). When a single selection is required (default opener, same-pattern priority), the user chooses. Replacement is “disable A, enable B”.

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.

Rendering tracks

The Host chooses a rendering track by interaction density: descriptors (status items, commands, light blocks) are drawn by Host components; structure surfaces (tab, panel, kanban view, settings page) default to Module Federation; document-style UI and artifact.editor use an iframe App surface.

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.

Official product plugins live in the marketplace official category. Install them from the marketplace tab or CLI. They start disabled and can be uninstalled. The Host family still ships official MCP binaries. Bytes on disk are not an installed plugin. After the runtime is on disk, enable still has to be turned on. Agent-side tools enter later new or rebound conversations. UI and Provider contributions appear on enable. The switch lives on the plugin itself. Official packages use the same public SDK as third-party packages.

Plugin	Effect after enable
Session Enhance	Questions, live feedback, session lookup, and session control
Multi-agent	& as a delegation mention; depth and child defaults apply to delegated children
Workflow Creator	Source edit, validate, debug, and publish
VibeX Office	Skills, workflows, and read-only preview for DOCX / XLSX / PPTX
Plugin Development	Author Skill and references; install from the official category when you need that product
Remote SSH	Install and start a remote Host over SSH, save it, and open a new window attached to it

Official reference plugins demonstrate public contribution points on the same install path:

Plugin	Contributions shown
Host chrome sample	app.command / app.toolbar / app.status / app.composer.slash / app.timeline.card / app.settings.section
Structure-surface sample	app.tab / app.panel / app.kanban.view / app.composer.action / app.settings.page
Environment-variable provider import	provider.model.importSource

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. Native Workflow Studio does not depend on the Workflow Creator plugin. Uninstalling Remote SSH keeps saved Hosts by default.

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

Relation to Settings

Session tools and the delegation master switch live on those plugins’ Config tabs. Office preview idle timeout, Workflow Creator’s default completion policy, and Remote SSH host fields also live in each package config. Install from Settings → Plugins → Marketplace.