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.