The marketplace publishes reviewed VibeX Plugins. Settings → Plugins → Marketplace reads the same Catalog. The same install command also accepts a Git repository, a GitHub Release, or a local .vxp. The package stays on that Host; it is not copied to other machines.

Start at the plugin marketplace and the Host marketplace tab. The contract is in the developer docs. Enable, disable, and uninstall are 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, snapshots land in ~/.vibex/imports/ and linked development directories go to ~/.vibex/imports/links.jsonl. Desktop or Server imports them on the next launch. Default URL is http://127.0.0.1:17891; override with VIBEX_URL / VIBEX_TOKEN.
4. list, update, and remove need a running Host.

Install command

Open the plugin marketplace, open the plugin page, and copy the Installation command:

npx vibex plugin add https://vibex.xforever.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>. The explicit form is equivalent:

npx vibex plugin add --web https://vibex.xforever.xin/marketplace/<author>/<plugin>

Git repositories use --web. Pin the tree with #tag, #branch, or #commit:

npx vibex plugin add --web https://github.com/<owner>/<repo>#v1.0.0
npx vibex plugin add --web github:<owner>/<repo>#v1.0.0

Without #, the default branch is installed and the source is unlocked. To follow later versions with plugin update, reinstall from a URL that includes #.

A GitHub Release that ships a .vxp is downloaded as that asset. A GitHub digest or a sibling .sha256 is verified when present:

npx vibex plugin add --web https://github.com/<owner>/<repo>/releases/tag/v1.0.0

A local .vxp, zip, or other plugin archive:

npx vibex plugin add --profile ~/plugins/search.vxp

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

After the command, open Settings → Plugins. A new install starts disabled. After enable, UI and Provider contributions appear immediately; Skills and MCP enter later new or rebound sessions. If the command says Desktop will import on next launch, quit VibeX fully and open it again.

The marketplace tab shows a Full Trust confirmation before install. Origin lock is marketplace or github. When a newer tag or semver appears remotely, Installed shows Update available. Marketplace installs ask the Catalog; GitHub installs ask that repository.

Prefer the marketplace page URL when the listing exists. Linking a development directory is an author path: add --dev only links; hot reload is vibex plugin run dev. See Development workflow.

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. One identity cannot use two sources at once; if the ID is already in the catalog, keep the current source or replace it.

What the command does

plugin add runs in this order:

1. Detect a marketplace page, a Git repository, a GitHub Release, an archive URL, or a local file.
2. For a marketplace page, call /api/marketplace/v1/artifact/<author>/<plugin>?tag= and follow the published download URL, sha256, and identity tuple.
3. Clone a Git repository at #ref; download a Release .vxp and verify SHA-256 when a digest is present; unpack a local archive.
4. Look for .vibex-plugin/plugin.json, validate the product package, and write ~/.vibex/imports/<plugin-id>-<version>.vxp.
5. Record origin, gitRef, gitSha, and whether the source is locked. 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, an unreadable archive, or a Release with no .vxp fails the same way. A download that advertises a digest and does not match SHA-256 aborts.

List and update

npx vibex plugin list
npx vibex plugin update <plugin-id>
npx vibex plugin update <plugin-id> --ref v1.3.0

list is the Installed catalog, including source and lock. update fetches another snapshot from the locked origin; --ref selects a new tag, branch, or commit. Linked development plugins do not use update: edit the source directory and the Host reloads when the digest changes. A snapshot with no locked origin must be reinstalled from a URL that includes #tag.

After install

The catalog lists the plugin. Marketplace, Git, and local-archive installs can be uninstalled. Config, disable, and uninstall are in Install and enable a Plugin.

To ship your own package, follow Development workflow, run pack, then npx vibex plugin publish. Git distribution puts the tag in the install command. A GitHub Release includes both the .vxp and a .sha256.

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.