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.