Opening a project shows the session board. A conversation is a durable chat between you and one agent. History lives in the event log; finished turns remain after you close a panel or restart the app.

One project can run many conversations at once. Each conversation binds to a workspace: the project root, or a Git worktree cut from that root.

Three pages

From left to right the board has three pages: the four-column board, Session hub, and Usage. Use Go to session hub and Go to usage stats at the top right. Subpages return with Back to board and Back to session hub.

Four-column board

Columns are To Do, In Progress, To Review, and Done. Drag a card to change status. Click a card to load it into the session execution pane on the right, where you read the timeline and type.

New session at the top of the board opens the creation dialog.

Session hub

The hub splits the same work into three zones:

• Session list on the left: sessions by status, with workspace and agent filters, sort, archive, and bulk delete.
• Session monitor in the middle: up to four live outputs. Move to execution area or Open in execution area puts one of them on the right.
• Session execution on the right: the focused conversation, where you send messages, answer permissions, and read turn results.

A list row can Rename session, Fork session, Delete session, or Export as Markdown / HTML. Delete skips sessions that are still running.

Usage stats

Usage stats shows token spend by project, conversation, and model, plus official subscription quota for some agents.

Layout

Left-to-right order is configured under Settings → Appearance → Page layout. Kanban and Workspace are saved separately. Full write-up: Page layout. Splitters on the page still resize widths. The toolbar can show or hide each zone and Reset Kanban layout.

New session

Entry points: New session on the board, or New session in the session list.

Dialog fields:

• Coding agent: enabled, available agents. If the list is empty, Manage Agents…
• Config: that agent’s session options, such as model and mode. Save as agent defaults stores them.
• Creation method: Existing workspace uses a directory or worktree you already have. New workspace creates a Git worktree from the target branch, then creates the conversation in it.
• Workspace branch: which tree to bind, or which branch to cut from.
• Session name: optional. Empty uses the first message.

Click Create Session to enter the execution pane.

Settings → General → Session creation can turn on Allow choosing a previous session to continue. When that is on, the agent can list sessions, and you picked an existing workspace, the dialog shows Choose a previous session to continue with Connect or Import. Import local agent conversations on the same General page scans conversations already on disk and imports them into a project.

For parallel code changes, give each conversation its own worktree. See Worktree. A worktree-bound conversation shows a Git bar above the execution pane. Rebase brings the target branch onto the current tree. Rebase back then merges the current tree onto the target branch.

Send and queue

When the conversation is idle, sending from the composer starts a new turn. While a turn is in flight, further sends join the message queue. Queue rows support Edit queued message, Move queued message up / down, and Delete queued message.

Send shortcuts live in Settings → Shortcuts: Enter to send, or Ctrl / Cmd + Enter to send with Enter inserting a newline.

Stop, resume, and fork are in Turns: stop, resume, fork.

A turn is one full cycle from your send to the agent finishing. A conversation has at most one in-flight turn. Controls live in the session execution pane: the composer, timeline error cards, and the session list menu.

Send, queue, steer

When idle, type in the composer and send to start a new turn. Shortcuts are in Settings → Shortcuts.

While a turn is in flight, further sends join the message queue and are claimed in order after the current turn ends. Queue rows can be edited, reordered, or deleted.

Some agents accept extra guidance on the in-flight turn. A field labeled Steer this turn appears above the composer; Send writes into that turn. Agents that lack this capability hide the field.

After you enable Session Enhance in Settings → Plugins, later new or rebound conversations can also let the agent ask you questions and read conversations you mention.

Cancel

Cancel the in-flight turn from the composer. The event log records Cancelled. Timeline content and files already written stay. To restore files, Undo under that turn rewinds the workspace to the checkpoint taken before the message; the conversation record stays.

Rollback to here on a user message truncates later generation so you can edit and resend.

Failure and retry

A failed turn shows an error card. Titles you may see: Cancelled, Agent session expired, Cannot resume the original session, Cannot load the agent session, Agent unresponsive, Connection closed, Authentication required.

Actions on the card:

• Reload session loads the existing agent session again.
• Rebind session, after confirmation, attaches a new cold-start session to this conversation. VibeX history stays. Hidden agent-side context starts empty; write anything the new process needs in the next message.

Agent unresponsive is often a network path to the model, or a login that expired. Return to Settings → Agents for preflight and authentication, then send again.

Interrupted

If the Host exits, crashes, or is killed during a turn, startup recovery marks the leftover in-flight turn Interrupted so the conversation can accept a new turn. Files may already have changed. Continue by sending another message.

Fork

Fork session on a list row copies the visible history into a new conversation with its own later turns. The original in-flight generation is left alone. If the agent fails to continue hidden context, the UI reports that history was copied and agent context was omitted.

Give the forked conversation its own worktree for parallel edits. See Worktree.

When the agent wants to write a file, run a command, change Git, or call an MCP tool, the turn pauses on the timeline until you Approve or Deny. Opening a project folder and the built-in browser are done by the app.

Where it appears

Pending requests show in the session execution timeline. Buttons are Approve and Deny. Deny can Provide a deny reason, which is sent back to the agent.

Settings → Shortcuts can bind Approve pending approval and Deny pending approval.

The same request is one shared state on desktop, WebUI, paired devices, and authorized chat channels. After one person answers, every other entry sees the result.

How to decide

Read the tool name, path, and command before you approve. Approval releases this one call. Code review, commit, and push stay separate steps.

If parallel conversations share a workspace, a destructive command affects files the others are reading. Give coding conversations their own worktree. See Worktree.

Tools from an MCP still request as the current agent. The name comes from that MCP; you are confirming this call.

Notifications

Settings → General → Notifications can play a sound or show a system notification on permission requests, prompts, and completed conversations. Timing is Only when unfocused or Always.

Remote approval

A paired phone companion can answer the same request. See Phone companion.

In Settings → Chat channels, when the authorized sender list is non-empty, that IM can approve or deny. An empty list closes inbound commands on that channel. See Message channels.

A project is your code folder. Conversations created in it bind to the project root by default. Isolated work uses a Git worktree. The file tree, terminal, Git, and preview are all relative to the workspace bound to the current conversation.

Entry points

The desktop home Get Started section has three actions:

• Select Folder opens an existing directory.
• Create New Project makes a folder at a location you choose.
• Clone Repository clones from a Git URL, then opens it.

Recent Projects lists folders you opened before. Left-click opens; right-click can delete. Deleting a project removes conversations and workspace data under it.

Select folder

The dialog title is Select folder. Choose folder picks a local directory.

A recognized Git repository can Open folder immediately. A folder that is not yet a Git repository is initialized first; the button reads Initialize Git and open.

Create new project

The dialog title is Create new project. Fill in Project name, Choose location for the parent directory, and optionally a short description. You can create README.md, .gitignore, and an MIT LICENSE. Create project makes the folder and initializes Git.

Clone repository

Clone Repository on the home screen. Enter the URL, pick Clone to as the parent directory, then Clone. The folder is added to the project list and opened.

After it opens

The project opens on the session board. New session there picks an agent and a workspace. Conversations bound to different worktrees in the same project can see different files and Git state, because each tree is the read/write root.

Per-project Git worktree behavior is in Settings → Worktrees. Global defaults are in Settings → Version control. See Worktree.

A worktree is an extra working tree cut from the same Git repository. Bind each coding conversation to its own tree so parallel tasks edit separate uncommitted files. The project must already be a Git repository.

Create one with the session

On the board or session list, click New session. Set Creation method to New workspace.

New workspace creates a Git worktree from the selected target branch, then creates the conversation in that tree. The hint reads: create a new worktree workspace from the target branch, then create the session in it.

Existing workspace binds a directory you already have. You can pick the current project-directory branch, or an existing worktree branch. A row marked not a worktree, will checkout first switches checkout before binding.

A worktree-bound conversation shows a Git bar above the execution pane:

• Rebase: choose a target branch and rebase its latest commits onto the current worktree.
• Rebase back: rebase the target onto the current tree, then merge the current tree back onto the target.

Merge, push, and publish wait for you. Inspect the diff, then commit in the Git panel. See Git and review.

Lifecycle commands, the count cap, the global workspace directory, and the branch prefix are configured under Settings → Worktrees. See Worktree settings.

Automations also create an independent worktree per run by default. See Automations.

Worktrees owned by a running turn or automation run are kept. Delete them as Git worktrees; removing the folder in the finder leaves stale registrations.

Git and review look at the workspace bound to the current conversation: the project root or a worktree. After the agent edits files, inspect the diff, stage, and commit here. Commit and push stay in the Git panel.

From the conversation

When a turn changes files, the timeline shows N files changed. Open it, or View diffs, to jump to review for that workspace.

The same card has Undo, which restores the workspace to the checkpoint taken before the message. The conversation record stays.

Review tab

In Workspace, New tab → Review opens the full diff for the current workspace. N files changed can expand or collapse every file. With a clean tree the pane reads No changes yet.

Diffs switch between file view and diff view. Review comments stay in VibeX so you can compare the agent’s explanation with the patch. To put the same discussion on the host, write it again on the pull request.

Git actions

Sidebar Git actions and the conversation card cover stage, commit, branch, and stash.

Stash stores current changes, then Pop or Apply later. The button is disabled when there is nothing to stash.

Worktree-bound conversations also get Rebase and Rebase back above the execution pane. See Worktree.

Creating a pull request, merging, and pushing need local Git credentials, and GitHub CLI installed and logged in when you use GitHub.

Version control settings

Open Settings → Version control.

• Git version settings: detect system Git, or set a custom Git executable.
• Commit reminder: when uncommitted line changes pass a threshold, send #commit_changes. Full write-up: Commit reminder.
• PR settings: prepare a description draft when creating a PR; the prompt is editable.
• GitHub account: detect gh, install GitHub CLI, log in or log out. Enterprise hosts can set a custom hostname.

Handle conflicts, rebases, and force-pushes the way you usually do. The remote repository changes when you push or create a PR.

The file tree starts at the workspace bound to the current conversation. Paths the agent can edit are the paths on that tree. Workspace region order is in Page layout.

File explorer

The File Explorer sidebar browses the current workspace. Expand folders and open files. Common text and code preview in the workspace. Open folder picks a different local directory; the empty state reads No folder selected.

Open in file manager uses Finder or File Explorer. The default external editor is chosen in Settings → General → External editor. The list marks each command’s PATH availability.

Search

Sidebar search finds implementations, config, and docs by keyword, relative to the current workspace. Case, whole word, and regex are toggles. Include and exclude file patterns are optional.

Preview and Office files

Preview font size is in Settings → General → Preview. The same section also has:

• files changed collapsed by default
• AI messages collapsed by default
• Hide model thinking
• Link open behavior: system browser, or built-in browser (Web Preview)

High-fidelity preview of .docx, .xlsx, and .pptx needs the built-in VibeX Office plugin. Opening those files starts a read-only preview. If OfficeCLI is missing, the pane offers Install OfficeCLI. Legacy .doc / .xls / .ppt are out of scope. See Install and enable a Plugin.

New tab

New tab in the workspace can open Browser, Review, Note, or Terminal. Review is in Git and review. Terminal is in Terminal. Browser is in Browser.

A patch card on the timeline opens the matching path in the same workspace. A worktree-bound conversation keeps its uncommitted files on that tree.

The terminal’s working directory is the workspace bound to the conversation. Use it to start a dev server, run tests, or execute project scripts. Commands run on the Host.

Entry points

In Workspace, New tab → Terminal. Open terminal on the welcome pane starts the same capability. Several terminal tabs can stay open.

The default program is Settings → General → Terminal. Default terminal set to the built-in shell runs inside the app. Warp opens the external app on the current workspace.

The monospace font in Settings → Appearance applies to code, the terminal, and diffs.

Use

Check the prompt path; it should be the current workspace. Long-running jobs belong in their own tab, separate from commands the agent is running.

When the agent asks to run a command, the timeline still shows a permission prompt. See Permission prompts.

Closing a terminal tab leaves Host processes running. Stop a service in that terminal, or use Stop dev server on the preview toolbar.

Remote

When another desktop connects as a workstation, the terminal still executes on the Host and streams output over the remote protocol. Full terminal entry points are on the Host or a workstation desktop.

The built-in browser previews local dev servers and pages. It runs on the Host. The tab is Browser. The empty state says Enter a URL to open a page.

Entry points

In Workspace, New tab → Browser. Links in a conversation follow Settings → General → Link open behavior: system browser, or built-in browser (Web Preview).

The dev preview pane is available after a workspace is bound. The toolbar has Refresh preview, Copy URL, Open in new tab, and Stop dev server. If no server is detected, the pane can Start dev server, or you can use the #start_dev_server instruction in the composer.

To click page elements and jump back to the editor, the preview pane offers Install Companion. Installing Web Companion restarts the dev server.

Capabilities

Multiple tabs, common device sizes, DevTools, Console, and Network. Opening the built-in browser is done by the app. When the agent operates the page, reads the console, or clicks for you, the timeline shows a separate permission prompt. See Permission prompts.

Preview URLs that go through the Host preview proxy only map to registered local ports and use a short-lived lease.

On pure Wayland Linux, CEF needs XWayland. If the window fails to start, follow the Linux notes in Install the desktop app.

Delegation lets the parent agent in the current conversation hand part of the work to another enabled agent. The child conversation has its own timeline and turns. The parent keeps the relation, policy, and a result summary.

This comes from the built-in Multi-agent plugin. After the plugin is enabled, the composer treats & as a delegation mention.

Enable the plugin

Open Settings → Plugins, select Multi-agent, and turn it on. The package ships with the Host, starts disabled, and stays in the catalog.

The Host then injects the delegation MCP into later new or rebound sessions. To delegate, start a new conversation, or Rebind session on an error card.

Parent and child agents both need Enable and authentication in Settings → Agents. See Enable and authenticate.

Start a delegation

Type & in the composer and insert an agent. That structured mention asks the parent to consider handing work over. The parent actually creates a child by calling the delegation tool. It may also finish the work itself, or ask you first.

If the parent lacks companion support, the UI says the mention stays a reference.

Plugin config

On the plugin Config tab:

• Max delegation depth limits root → child → grandchild, 1–8, default 1.
• Completed result cache (MB) caps in-memory cache for running delegations. 0 means no cap.
• Sub-agent defaults apply only to new child conversations started by delegation.

Saves write this plugin’s config.json and apply to later new or rebound sessions.

While it runs

The parent timeline shows a delegation card. The execution pane lists child conversations; Open child conversation opens one. Child turns follow the same rules as any conversation: one in-flight turn, file and shell calls still need approval.

The parent receives a summary and whatever return payload you allowed. Closing the parent pane leaves child turns running. Stop them in the child conversation, or Cancel delegation on the card.

For a fixed, versioned step graph, use Graph Workflow. For a timed or on-demand repeat, use Automations.

A Graph Workflow is a step dependency graph. The source file can be saved repeatedly. A published definition version is immutable. An automation binds one published version.

Edit, validate, debug, and publish come from the built-in Workflow Creator plugin.

Enable the plugin

Open Settings → Plugins, select Workflow Creator, and turn it on. The package ships with the Host, starts disabled, and stays in the catalog. The loopback gateway starts while the desktop Host is running.

After enable, open *.vibex-workflow.json in a workspace to enter Workflow Studio. The source file is the authoring fact and can go into Git.

Work in Studio

Save and validate the graph first. Debug runs can execute only the selected step, or continue downstream from it. Debug uses an isolated test worktree. If you are not already in a worktree, the app offers Create test worktree.

Step kinds:

• An Agent step completes through a child conversation and real turns.
• An Approval step waits for an authorized principal.

Default Agent step completion on the plugin Config tab is Automatic or Manual confirm. It applies to new steps that omit a completion policy in the source.

A retry creates a new attempt and keeps the old evidence.

Publish

After validation, Publish Workflow. Publish produces an immutable version. Later source edits prepare the next version. Runs that already started keep the version they bound.

To run a workflow from automation, create an automation with target type Workflow and bind this published version. A later publish leaves older automations on the version they already reference. See Automations.

Run control

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

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 starts a new turn in the original child conversation.

Merge, push, publish, and deploy stay in Git and review.

An automation starts a real turn, or a published Workflow version, when you run it by hand or when the schedule fires. Each run leaves an auditable Conversation and Turn.

Entry point

Open Settings → Automations. From the empty state, New or a starter template. Templates fill an editable draft. Saving and running stay manual after you edit the draft.

Create

New asks for a type first. The type is fixed at creation:

• Single session: each run creates a real turn with the chosen agent, workspace, and prompt.
• Workflow: runs one published Workflow version. To target a different version, create another automation.

The form includes name, project, agent or workflow, prompt, branch, isolation, and trigger.

Isolation:

• Create an independent worktree per run (default)
• Share the project root: uses the current checkout. The backend rejects a dirty tree or a mismatched branch, and it will not merge, push, or publish.

Trigger is Manual or a schedule. A schedule can preview the next five runs. Timezone is an IANA name.

Save when the form is complete. The list switch is Enabled. A disabled row is skipped by the scheduler.

Run and history

Run now fires one execution immediately. Run history lists Running, Completed, Failed, Cancelled, Interrupted, and Skipped. A running row can Cancel run. Workflow targets offer Open Workflow.

Import and export

Copy spec JSON copies a document that omits database identity, secrets, and machine paths. Import JSON pastes it and leaves the row disabled until you enable it. Import resolves project, agent, and workflow references on the current Host.

Engine owner

For one data directory, only one automation engine owner exists at a time: the current desktop or vibex-server. Only the owner claims due jobs. If the page says the engine is held by another host, the view is read-only until that process releases it.

On Host startup, leftover direct-turn runs become Interrupted. Runs already attached to a Workflow run follow that run’s terminal state. Neither is fired again automatically. While the Host was down, at most the most recent missed schedule is backfilled.

Finished runs and their independent worktrees are kept for 30 days by default, under a per-directory space quota. Running runs stay until they finish.

A Host is the VibeX process that owns the data directory and serves the remote protocol: this machine’s desktop app, or vibex-server. Another desktop, the browser WebUI, and a phone companion all connect to it.

Everyday single-machine use is the desktop app. Open remote listening, or switch to Server, when other devices must connect or you want a headless process. Headless setup is Install Server and WebUI.

If a Server already holds the data directory, a second desktop attaches as a client.

Open remote listening

Open Settings → Remote connection.

Service status is Running or Stopped. One listen port serves both the Web UI and the remote protocol. Default port is 17891.

Access configuration:

• Listen port: browsers and paired devices use this port. Probe reports the port’s availability.
• Auto start: open Remote Protocol when the app launches.
• Allow LAN: listen on all interfaces. Public access needs a TLS reverse proxy in front.
• Access token: generate and copy. The full value is shown once; save it before leaving the page.

Save, then Start. Status shows this-computer, LAN, and published addresses. Copy address or Open.

Listening defaults to loopback. Turn on Allow LAN before a phone scans; a 127.0.0.1 QR is unreachable from the phone.

Device pairing

Device pairing on the same page issues a five-minute code that can be redeemed once.

Device class is Companion or Workstation:

• A workstation can use conversations, Git, terminal, and plugin management. Host listen settings, admin token, backup/restore, and upgrades stay on the Host under Settings → Remote connection and System. Backup steps: Backup and restore.
• A companion is narrower. See Phone companion.

Click Generate connection code. The other device scans the QR or types the code. Long-lived credentials go in the system keychain or Android Keystore.

Paired devices lists redeemed devices. Revoke forces a new pairing before that device can connect again.

Desktop and Server must be in the same version family. A capability mismatch fails the pairing.

WebUI

Open the Web UI address from the status section in a browser. Agents, Git, and the terminal still execute on the Host. Use the host address and access token from this page.

While the Host is offline, clients read the supported offline cache. New turns and permission answers need the Host online.

The Android companion connects to a Host you control. On the phone you read conversations, send input, and answer permissions. Agent processes, the plugin kernel, and Git writes stay on the Host. The current companion is Android.

Prepare the Host

1. Keep the Host online: this desktop or vibex-server.
2. Open Settings → Remote connection, save, and Start.
3. Turn on Allow LAN so the phone can reach a non-loopback address.
4. Set Device class to Companion, then Generate connection code.

Pair on the phone

Open the Android app and scan the QR or type the one-time code. Credentials stay in the system keystore and reconnect later.

The code lasts about five minutes and can be redeemed once. Keep the pairing code and access token on the pairing UI and in the system keystore.

What you can do

• Read the timeline, send input, cancel an in-flight turn, and steer.
• Approve or deny permission requests. The result matches desktop and writes the same event log.
• Read supported artifacts and the offline cache.
• Receive terminal-state notification summaries.

Where the rest lives

Plugin authoring, Workflow and automation definitions, a full terminal, and Git commit/push stay on the Host or a paired workstation desktop.

Plugins add product capabilities to the current Host. A package may ship Skills, MCP, Workflows, or UI. Open Settings → Plugins (Plugins in the settings sidebar). Newly installed packages start disabled. Contributions become visible after you enable them.

The page

The catalog lists packages on this Host. Built-in packages show VibeX built-in and remain in the catalog; the switch only enables them. Click a row for Content and Config.

Import plugin installs a local package or a linked development directory. Third-party packages stay on this Host. Published marketplace packages: Install a Plugin from the marketplace.

Built-in packages

Shipped with the Host, disabled by default:

• Session Enhance: questions, live feedback, session lookup, and session control.
• Multi-agent: parent agents delegate subtasks; & appears in the composer. See Agent delegation.
• Workflow Creator: edit, validate, debug, and publish a DAG. See Graph Workflow.
• VibeX Office: create, analyze, and preview DOCX / XLSX / PPTX. See Files and preview.
• Plugin Development: a local dev interface for authors. Everyday use can leave it off.

Open a row, read the summary and contents, then enable. The first enable projects compatible Skills, MCP, or Workflows onto installed, enabled agents.

Later new or rebound sessions receive those tools. Sessions that were already open keep the tool list from creation.

Config

Config edits that package’s config.json, for example the four Session Enhance toggles, Office preview idle timeout, or Workflow Creator’s default completion policy. Saves apply to later new sessions or new previews. Instances already open keep their current settings.

Disable and uninstall

Turning enable off stops new turns from using the package’s contributions. History already in the event log stays.

Third-party installs can Uninstall plugin. Uninstall removes membership, agent bindings, and Skill projections. Conversation and automation history remain. Built-in packages are disabled with the switch.

A workstation desktop can change plugin facts on the Host through the application core. The management UI is Settings → Plugins.

To write a plugin, see Developer docs.

The marketplace publishes reviewed VibeX Plugins. Install with a local command or import a .vxp into the current Host. The package stays on that Host; it is not copied to other machines.

Start at the plugin marketplace. The contract is in the developer docs. Enablement is in Install and enable a Plugin.

Before you start

1. VibeX desktop is running, or npx vibex serve has started a Host.
2. The shell can run npx vibex.
3. If desktop or npx vibex serve is running, plugin add finds the local Host token and imports into the catalog. If no Host is up, the package lands in ~/.vibex/imports/ and Desktop imports it on the next launch. Default URL is http://127.0.0.1:17891; override with VIBEX_URL / VIBEX_TOKEN.

Install command

1. Open the plugin marketplace and open the plugin page.
2. Copy the Installation command. The full form is:

npx vibex plugin add https://vibex.xforver.xin/marketplace/<author>/<plugin>

Replace the URL with the plugin page on the site you are using. A local preview host is http://127.0.0.1:3100/marketplace/<author>/<plugin>.

3. Run it. The CLI asks the marketplace for a download URL, unpacks the .vxp, validates the product layout, writes a deterministic package, and imports it when a local Host is available.

4. If the archive contains more than one package, add --plugin <plugin-id>. Use --yes when stdin is not a TTY.

5. Open Settings → Plugins. A new install starts disabled. Enable it so Skills, MCP, or UI reach later new or rebound sessions. If the command says Desktop will import on next launch, quit VibeX fully and open it again.

A GitHub repository also works: npx vibex plugin add https://github.com/<owner>/<repo>. Prefer the marketplace page URL when the listing exists.

Import a package file

The plugin page offers Download package. After you have a .vxp (or zip / tar.gz):

1. Open Settings → Plugins.
2. Choose Add plugin or Import plugin and pick the file.
3. Confirm identity and permissions, then install.
4. Enable the row in the catalog.

Dropping a .vxp onto the plugins page is the same as choosing a file.

What the command does

plugin add runs in this order:

1. Detect a marketplace page, a GitHub URL, or a local file.
2. For a marketplace page, call /api/marketplace/artifact/<author>/<plugin> and follow the published download URL.
3. Unpack the archive and look for .vibex-plugin/plugin.json.
4. Validate the product package and write ~/.vibex/imports/<plugin-id>-<version>.vxp.
5. If a token is present and install is confirmed, call Host plugin_control_import.

Unpublished submissions have no marketplace download URL, so the command fails. A broken layout or an unreadable archive fails the same way.

After install

The catalog lists the plugin. Built-in rows show VibeX built-in; marketplace installs can be uninstalled. Config, disable, and uninstall are in Install and enable a Plugin.

To ship your own package, follow the developer docs, run vibex plugin pack, then submit the .vxp on the marketplace.

Page layout sets the left-to-right order of the main window regions. Kanban and Workspace each keep their own arrangement. Dragging changes order only. Width belongs to the region itself and stays the same after a swap.

The same settings page also has theme, UI zoom, monospace font, and language. This article covers region order only.

Entry point

Open Settings, then Appearance. Scroll to Page layout. The schematic has two blocks: Workspace page and Kanban page.

The main-window toolbar can show or hide Kanban regions and offers Reset Kanban layout. That is a per-window shortcut. The arrangement saved in Settings is separate.

Kanban page

Kanban has three regions:

• Session list: board columns and session cards.
• Session monitor: status and usage for the selected session.
• Session execution: timeline, composer, and execution area.

Hold a region in the schematic and drop it on another region to swap them. Save settings at the bottom of the page; the main window then follows the new order. Dragging without saving leaves the main window unchanged.

Restore default returns the Kanban schematic to the factory order. Save still required to write it back to the main window.

After save, splitters on the page still resize regions. Hiding a region from the toolbar affects the current window only and leaves the saved order unchanged.

Kanban usage: Session board.

Workspace page

Workspace has four regions:

• Sidebar panels: file tree, Git, review, and related sidebars.
• Workspace: files and preview.
• Session: timeline and composer.
• Terminal: the built-in terminal.

Same mechanic as Kanban: drag to swap in the schematic, then save. Restore default applies to the Workspace schematic only.

Files and preview: Files and preview. Terminal: Terminal.

Save and sync

Layout is stored in local frontend preferences. After the settings window saves, the main window syncs through a storage event and rearranges immediately. All windows share one arrangement.

Theme, zoom, and language changes leave layout unchanged. A new machine needs the arrangement set again. Moving Host data is described in Backup and restore; the backup preview lists the files actually included.

Prompt enhancement uses an enabled Agent to rewrite the draft in the session composer into a clearer, actionable prompt, then writes the result back into the composer. It changes the draft only. No turn is started. Original intent stays the same.

Entry point

Open Settings, then General, then Prompt enhancement. Turn on Show prompt enhancement button. The session composer toolbar then shows Prompt enhancement.

That Agent must already be enabled and ready under Settings → Agents. If the list is empty, finish Enable and authenticate first.

Configuration

In the Prompt enhancement block:

• Agent: the rewrite Agent. Changing Agent clears mode and session config chosen here.
• Refresh session controls: reload that Agent’s current modes and options.
• Mode and session config: the same kind of options as Create session, for example model. They apply only to the rewrite call.
• Use custom enhancement prompt: off uses the built-in system prompt; on lets you edit it. The built-in prompt requires JSON with exactly one top-level field, EnhancedPrompt.

Save settings afterward. Until save, the composer button still uses the last saved configuration.

A rewrite consumes that Agent’s quota or API budget under the same rules as a normal turn.

Usage

Type a draft in the session composer, then click Prompt enhancement. An empty draft or whitespace-only draft produces no request.

On success, the composer text is replaced with the rewrite. Review it, then send to start a turn. On failure, the error appears on the composer and the original draft stays.

The rewrite request includes the current session and workspace ids, plus recent messages, so the rewrite Agent can resolve ambiguity. The built-in system prompt requires using that context only when it materially helps, omitting a conversation summary from the result, and omitting Markdown fences or extra fields.

Turning it off

Turn off Show prompt enhancement button and save. The composer hides the button. Text already in the composer is unchanged.

Import local sessions scans official conversation history that an enabled Agent already stored on this machine, writes the selected items as VibeX conversations, and attaches them to a chosen project workspace. After import they appear on the board and in the session list for viewing and sending. The Agent’s original files stay in their official directories.

This is separate from Continue a previous session when creating a conversation. That path binds an Agent-native session id in the create dialog. This feature writes VibeX conversation records in bulk.

Entry point

Open Settings, then General, then Local conversations, then Import. The Import local conversations dialog opens.

You need at least one enabled Agent and at least one opened project. With no project, destination pickers in the dialog stay unusable. Open a project first: Open a project.

Scan

Choose an Agent at the top of the dialog. The scan of that Agent’s local history starts immediately and groups conversations by folder. With exactly one enabled Agent, opening the dialog selects it and starts the scan.

While scanning, the dialog shows Scanning local conversations…. On failure it shows the reason and Retry.

Results are grouped by folder. Each group shows the path, conversation count, and an Import into workspace. The search box filters by folder name, path, or conversation title. Only not yet imported hides items already imported.

Destinations and selection

Each folder needs an import target:

• When VibeX already matches a project or workspace, the dropdown is prefilled.
• Groups labeled Choose project require a manual project. With no project available, conversations in that group stay unchecked.

Check conversations to import. Select all covers importable items in the current filter that already have a target. Items marked Already imported stay unchecked.

Rescan drops the current checks and scans the same Agent again.

Import

Import (N) writes the selection. The dialog stays open until import finishes. When finished it shows three counts:

• Imported: new VibeX conversations.
• Skipped: a matching record already existed.
• Failed: rows that could not be written, with error text below.

Imported conversations appear on that workspace’s board and session list. Titles reuse the Agent-side name when present; unnamed conversations show Untitled conversation. Later send, permission, and Git actions match conversations created inside VibeX.

Close ends this pass. Open Import again for another batch.

Scope

Import writes the Host conversation store. Agent official config and auth files stay in place, for example Claude Code still uses ~/.claude. Deleting a VibeX conversation leaves Agent-side history in place. A later scan marks those items Already imported.

Commit reminder inspects uncommitted changes in the current workspace after a user turn ends. When added plus deleted lines strictly exceed the configured boundary, it hands the official instruction #commit_changes to the same Agent so it can review the diff and commit. Automation turns and internal turns skip this check.

The instruction body lives in Settings → Instructions in the official instruction market, id commit_changes. When a reminder fires, the Agent receives that body plus the current added/deleted line count.

Entry point

Open Settings, then Version control, then Commit reminder. Staging and committing in the Git panel remain manual, as in Git and review. This switch only controls the post-turn reminder.

Configuration

• Enable commit reminder: after this is on, a user-started turn that reaches a terminal state is measured.
• Reminder mode:
  • Separate reminder: start another turn immediately. The timeline shows #commit_changes. The Agent reviews and commits per the instruction.
  • Smart mode: record a pending reminder, then prepend the same instruction to your next user message on that conversation.
• Change line boundary: lines. A reminder fires only when added plus deleted lines are greater than this number. Equality skips the reminder.

Save Version control settings afterward. A very low boundary reminds after small edits; a very high boundary almost never reminds. The number currently shown on the page is the default in force.

#commit_changes tells the Agent to read git diff and git diff --staged, then stage and commit. The commit message format is a first line under 50 characters as <type>(<scope>): <subject>, a blank line, then a detailed body. Types include feat, fix, docs, style, refactor, perf, test, chore, revert. The actual commit follows the workspace diff.

Separate reminder

After a user turn completes normally, the Host counts uncommitted added and deleted lines in the workspace. Over the boundary, it starts the reminder turn. That turn’s origin is commit reminder, so a later reminder check skips it.

A workspace without a Git repository, or a failed count, skips this round. If a turn is already in flight on the conversation, the reminder waits until the conversation is idle.

Smart mode

After a user turn, if the count is over the boundary, the Host only sets pending reminder and starts no new turn. The next time you send on that conversation, the Host counts again. Still over the boundary, #commit_changes is prepended to your text. Already under the boundary, pending reminder is cleared and only your text is sent.

Turning the feature off, or switching the mode back to Separate reminder, discards a reminder that has not been sent yet.

Turning it off

Turn off Enable commit reminder and save. Later user turns skip the line count. A reminder turn already started is treated as a normal turn and can be stopped. To edit the commit-message template, open Settings → Instructions and edit the commit_changes body.

Worktree settings control where Git worktrees are created, how new task branches are named, and which commands each project runs on create and destroy. Binding a session to a tree is described in Worktree. This article covers the settings page only.

The project must already be a Git repository before a worktree can be created.

Entry point

Open Settings, then Worktrees. The page has two blocks: Global worktree settings at the top, Project worktree settings below.

Global worktree settings

These two fields apply to every project:

• Workspace directory: root used when creating task worktrees and temporary project directories. Type a path or Browse with the folder dialog. Empty uses the product default location.
• Branch prefix: default prefix for new task branches, for example vibex. The task id is appended after this prefix.

Empty prefix, spaces, a leading or trailing /, //, and the characters ~ ^ : ? * [ \ are rejected. Invalid input disables Save and shows the reason on the page.

Save in that block writes only these two fields. Project settings below are saved separately.

Project worktree settings

The Project dropdown lists projects you have opened. Each project has its own configuration. With no opened project, the dropdown shows No opened projects yet.

Lifecycle commands

• Command after create: runs after the worktree exists on disk and before the first session on that tree, for example pnpm install. Empty skips the command.
• Command before destroy: runs before VibeX deletes that worktree, for example pnpm run clean. A failing command cancels the delete; the tree stays so you can read the output.

Commands run on the Host machine. The working directory is that worktree. The toolchain those commands call must already be installed there.

Cleanup reminder

• Prompt before exceeding the limit: when on, creating another worktree that would push this project over the cap shows a confirmation.
• Worktree count limit: a positive integer. The page also shows how many worktrees the project already has.

The confirmation offers:

• Continue creating: create anyway, past the cap.
• View worktrees: abandon this create and go manage existing trees.

Worktrees owned by a running turn or automation run count toward the total and are kept on delete. Deleting the folder in the file manager leaves a stale registration, so the count drifts. Remove trees with the in-app Git worktree actions.

Save settings in the project block. Success shows Worktree settings saved.

Automations

Automations default to one independent worktree per run. They use this page’s global root and branch prefix. Project lifecycle commands run on that project’s trees. See Automations.

A message channel attaches this Host’s coding activity to Telegram, Feishu, WeCom, QQ, or a generic webhook. It is a bot configuration on the Host, separate from paired phones or workstations. Send and receive stay in the vendor IM apps.

Channel config and secrets live in the Host data directory. A remote workstation can start sessions. Creating, disabling, and rotating secrets stay on the Host machine under Settings.

Entry point

Open Settings, then Chat channels (Message channels). Three tabs: Channels, Commands, and Events.

Channels

Channels lists bots saved on this machine. New channel asks for:

• Name: the list label, required.
• Type: Telegram, Feishu bot, WeCom group bot, QQ bot, generic webhook.
• Credentials and chat binding for that type, next section.
• Enable channel: off stops event delivery and Test send. The row stays in the list.
• Authorized senders: one user ID per line. Inbound commands apply to the bound chat or group above, or to IDs on this list. Other messages are dropped. An empty list trusts only the bound chat or group.

After save, Test send posts a probe message. A row offers Edit channel, Delivery log, and Delete channel. Delete asks for confirmation and removes the secret as well.

Delivery log shows the latest delivery result and detail. On a failed send, read this log, then check credentials and network.

Telegram

Token from @BotFather. Optional chat id (negative for groups, numeric for DMs). Forum supergroups can enable Telegram topic mode: one topic per conversation; the general topic ignores plain text.

Feishu bot

App secret and group Chat ID. Groups usually require an @ mention before text is treated as a command.

WeCom bot

Add a group bot in the group settings, copy the key= value from the webhook URL, and paste it as the secret. Scan WeChat code binds a send/receive Weixin iLink bot.

QQ bot

OneBot HTTP URL for send. Optional forward WebSocket for inbound commands; empty derives it from the HTTP URL. Optional access_token. Message type is group or private, plus group id or QQ number.

Generic webhook

POST turn and permission summaries to an http:// or https:// URL. Events can add multiple URLs. Payload examples show JSON for prompt_started, prompt_finished, and similar events, with event, body, and source.

Commands

Commands sets the command prefix, for example /vibex. Authorized senders type prefix plus command in the IM. The usage list on this tab is authoritative:

• folder [n|name]: list projects, or pick by index or name.
• agent [n|id]: list agents, or pick by index or id.
• task <text>: send a task to the currently selected conversation.
• sessions: list recent conversations on this Host.
• resume [n|id]: select by index or conversation id and continue.
• cancel: cancel the in-flight turn.
• approve [always]: approve a pending permission; always keeps allowing that class of action.
• deny: deny a pending permission.
• search <keyword>: search conversations.
• today: list conversations created today.
• status: channel and Host status.
• help: list every command.

Put your own user ID in Authorized senders first, then colleagues. Permission and question cards posted to IM resolve the same pending request as the desktop. See Permission prompts.

Events

Events chooses which coding activities are pushed. Only checked items are sent:

• Task started: the Agent began a turn.
• Task finished: the Agent finished this task.
• Permission requested: approval or denial is needed in IM.
• Run error: the Agent reported an error.
• Connection status: Agent connection changed.
• Session created: a new conversation was created.
• Turn completed: a turn reached a terminal status.

Include prompt content in notifications is off by default. Off omits the raw prompt from a task-started notice so drafts stay out of IM. Turn it on and save when the raw text is required.

Daily digest is per channel and summarizes that day’s activity in the bound chat. The time shown on that channel row is authoritative.

Safety

Channels deliver summaries that omit secrets. Tokens, pairing codes, and .env stay in Host config. Point webhook URLs at receivers you control. After a channel is disabled or deleted, that IM stops receiving new events.

Run logs record diagnostics from the desktop app process. They are written to local files and kept in memory on the settings page for live viewing. Use them for startup failures, Agent connection errors, and Git or automation faults.

This page is in the desktop Settings sidebar. The current WebUI Settings sidebar has no Run logs item.

Entry point

Open the desktop Settings window, then Run logs.

Capture level

Capture level is the lowest severity written to files and to the viewer, from least to most:

• Off: recording stops.
• Error
• Warn
• Info
• Debug
• Trace
• All

Debug, Trace, and All write the most and grow files the fastest. Info or Debug is enough for routine diagnosis. Changes save immediately.

When VIBEX_LOG or RUST_LOG is set, capture level is locked. The page shows Capture level is locked by VIBEX_LOG or RUST_LOG, and the dropdown is disabled. Unset those variables and restart the app to change the level here.

Per-module overrides

Per-module overrides set a level on one module without changing the global capture level. Add picks a module name and a level. Remove deletes that override.

Modules include agents, application, automation, conversations, db, delegation, git, plugins, server, services, workflows, and others. Override only the module under investigation. Leave the rest of the process on the global capture level.

Recent logs

Recent logs shows the in-memory stream, up to 2000 lines. Tools:

• Pause / Resume: while paused the viewer stops appending; capture still writes files.
• Refresh: fetch again.
• Clear: drop the in-memory copy. Files on disk stay.
• Open folder: reveal the log directory in the file manager.
• Search: filter by message body or source.
• Level filter: show error, warn, and so on.

The footer shows Shown N / M. An empty viewer shows No logs.

If Open folder fails, check desktop permissions. Before attaching that directory to an issue, delete lines that contain paths, tokens, or raw prompts.

Versus the session timeline

Tool calls and Agent output on the session timeline belong to that conversation’s event log. See Turn control. This page is the VibeX desktop process’s own diagnostics: Host start, IPC, Git, plugin load, and similar.

Backup packs this Host’s VibeX data into a portable .vibexbak file, optionally encrypted with a passphrase. Restore requires a preview first, so overwrite targets are visible before write. Use it when moving machines, reinstalling the OS, or keeping a copy before clearing local data.

This page is under desktop Settings → System. The current WebUI Settings sidebar has no System item.

A backup covers VibeX’s own store and config. It omits project Git repositories and each Agent’s official directories (for example ~/.claude, Codex auth.json). Move those files with each Agent’s own tools.

Entry point

Open the desktop Settings window, then System, then Backup & Restore.

Export

Export backup asks for a destination path with a .vibexbak suffix. Encrypt passphrase is optional; empty packs without encryption. Click Export.

While running, the page shows Exporting VibeX backup.... Success shows Backup exported. An empty path shows Please enter a backup export path.

The archive typically includes:

• config.json, profiles.json, and db.sqlite from the Host data directory
• version-control-settings.json, instructions-metadata.json, system-settings.json
• web-service-settings.json, chat-channel-settings.json, chat-channel-secrets.json
• settings.json and mcp.json under the user VibeX directory, plus files under skills/

The preview after export, or the preview before restore, is the authoritative file list. Missing files on disk are left out of the pack.

Keep the file on a disk you control, or on an encrypted volume. Treat a pack that contains chat-channel-secrets.json and the database as confidential.

Preview

Restore backup first takes a .vibexbak path. Encrypted packs also need the decryption passphrase. Click Preview.

A successful preview shows format, version, app version, created time, file count, and paths that would be overwritten. Rows marked Will overwrite replace the live file on restore. A wrong passphrase or a damaged file shows Backup preview failed.

Preview must finish before Restore is available. Skipping preview shows Please preview the backup to restore first.

Restore

After preview, click Restore and confirm. While running, the page shows Restoring VibeX backup.... Success shows Backup restored. Restarting the app is recommended. After restart, conversations, channels, instructions, and settings match the backup.

Restore writes the current Host data directory and replaces files marked in the preview. Conversations, channels, and settings created on this machine after the backup are replaced by those files. Git commits inside project workspaces stay.

Failures

Export or restore errors show Backup export failed or Backup restore failed plus a reason. Typical causes: no write permission on the path, insufficient disk space, passphrase mismatch, or a file that is not vibex-portable-backup. Change the path or passphrase and preview again.

Clear local data returns this Host’s VibeX configuration, conversation store, and caches to a freshly installed state, then registers built-in Agent rows again. Git repositories on disk, worktree folders, and each Agent’s official directories stay in place.

This page is under desktop Settings → System. The current WebUI Settings sidebar has no System item.

Clearing is permanent. Keep conversations, channels, and settings by finishing Backup and restore first.

Entry point

Open the desktop Settings window, then System, then Clear VibeX local data. Click Clear local configuration and cache.

A confirmation dialog asks for a second confirmation. Confirm to start.

What runs

The Host stops scripts and processes still running. If a process stays running, the operation aborts. Stop it by hand, then retry.

It then deletes local config files and the cache directory, empties business tables in the conversation database, writes default settings, and registers built-in Agents again. Desktop toasts and file watchers reset.

While running, the page shows Clearing local data.... Success shows Local data cleared and asks the app to reload. After reload the board is empty. Open projects, enable Agents, and configure channels again.

Removed and kept

Removed or reset: VibeX settings, conversations and turns, workflow runs, message channel config, automations, plugin enabled state, local caches.

Kept: project folders and their Git history, Git worktree directories already created, each Agent’s official config and login (for example ~/.claude), and .vibexbak files you saved yourself.

Opening the same project afterward registers it as a newly opened repo. Worktrees that still exist on disk need a new bind as in Worktree, or cleanup with Git.

Failures

On Clear local data failed, wait for the current attempt to finish. Confirm no Agent or terminal process is stuck, then retry. If another program holds the database file, quit that program and retry.