Find your symptom below. Each section lists likely causes and the commands that check them. If nothing here helps, collect a debug bundle.
Start with this command. It checks your installation, terminal, sockets and integrations, and it prints a hint for each problem:
vibeke doctor
Vibeke does not start or cannot connect to the server
Likely causes: the shell cannot find vibeke, an old server is stuck, or the installation is damaged.
-
Run
vibeke --version. If the shell says the command is not found, addexport PATH="$HOME/.local/bin:$PATH"to your shell configuration and open a new terminal. See installation. -
Run
vibeke doctorand read every line markedwarnorFAIL. -
Run
vibeke server statusto see whether a server is running. -
If the server does not answer, stop it and start Vibeke again:
vibeke server stop vibekevibeke server stopleaves the pane processes running. They reconnect when the new server starts. See holders.
The option --no-spawn makes a command fail instead of starting a server. Use it when you want to check for a running server without starting one.
Agent state does not show in the sidebar
Likely causes: the integration for your agent is not installed, or you started the agent outside a Vibeke pane.
-
Start the agent in a Vibeke pane. Vibeke shows the agents that run in its panes.
-
Check the integrations:
vibeke integration status all vibeke integration doctor all -
If an integration is not installed, open Setup in the command palette (Ctrl+B, then :). Select the integration, press d to inspect the changes, and press i to install. You can also run
vibeke integration install claudeand replaceclaudewithcodex,pioromp. -
Start the agent again after the installation.
Without an integration, Vibeke reads the terminal output. This shows less detail than the integration does. See agents and interactions.
Answers do not reach the agent
Likely causes: the agent has no integration that can take answers, or the request was already answered or closed.
- Run
vibeke integration doctor all. It shows what each integration can do. - Open the request in the attention inbox (Ctrl+B, then i). The card shows whether Vibeke delivered the answer.
- Answer in the pane itself if the integration cannot deliver answers. Terminal detection can show a request, but the agent's own interface takes the answer.
- Vibeke keeps requests and delivery state after a server restart. It does not send the same answer twice.
See answer a request.
Images do not show in the terminal
Likely causes: your terminal does not draw images, or you run Vibeke inside tmux.
- The terminal interface draws images in terminals that support the kitty graphics protocol, such as kitty and Ghostty, and in iTerm2.
- Other terminals, and tmux, show a short text hint. Press
oon the image to open it on this machine.
See images in the terminal interface.
Keys do not work
Likely causes: another program takes the same keys, or you run Vibeke inside tmux.
Vibeke uses Ctrl+B as its prefix. tmux uses the same key by default. When you run Vibeke inside tmux, tmux receives the prefix first. Use one of these fixes:
- Press Ctrl+B twice. tmux then passes one Ctrl+B to Vibeke.
- Change the Vibeke prefix. Run
vibeke config editand setprefixin the[keys]section, for exampleprefix = "ctrl+a". Then runvibeke config validate.
To see what Vibeke binds, run vibeke keys, or press Ctrl+B and wait for the key menu. Vibeke reports key conflicts when it checks the configuration. See customize Vibeke and the configuration reference.
Phone pairing fails or the app shows offline
Likely causes: the host is asleep, the gateway is not running, the invitation expired, or the relay needs an account.
- Check that the host is awake and that a Vibeke session is running.
- Run
vibeke gateway statusto check the gateway and the relay connection. - Run
vibeke gateway logs -fto follow the gateway log while you try again. - Run
vibeke gateway pairfor a new invitation. An invitation works once and expires. A revoked device cannot reconnect either. - If you use
cloud.vibeke.dev, runvibeke whoamito check that you are signed in. Runvibeke loginif you are not. With--relay https://relay.vibeke.devno account is needed. - Compare the device fingerprint on the phone with the one on the host before you confirm.
The browser stores pairing keys for each origin. A different domain is a separate device and needs its own pairing. If the host is offline, the app shows the last saved state with the time it was captured. See phone and browser access.
Panes are gone after a restart
Each pane has a holder process that keeps the pane process running. The holder survives these events:
- You close the terminal or detach the client.
- The server stops, crashes or restarts, for example during
vibeke update.
The holder does not survive a restart of the host computer, or a failure of the holder itself. Those events stop the pane processes. Start the agent again in a new pane.
Run vibeke again after a server restart. Screen recovery can be incomplete, so a pane may show a partial screen until the program redraws. See holders and process recovery.
The desktop app cannot find the CLI
The desktop app does not include the host CLI. It looks for vibeke in the VIBEKE_BIN environment variable, in the usual install locations, and on your PATH.
- Install the CLI and check
vibeke --versionin a terminal. See installation. - In the app, select Choose… and pick the
vibekeexecutable, for example~/.local/bin/vibeke. - Start
vibekein your project and keep it running. Select Start gateway in the app if it asks. - On Linux, check that a Secret Service or keyring backend is available.
Windows has no host CLI. Connect to a remote host. See the desktop guide.
Collect a debug bundle to report a bug
A debug bundle is an archive with diagnostics. Vibeke passes it through redaction, which removes recognized secrets. Redaction is best-effort, so review the files before you share them.
vibeke debug bundle
vibeke debug bundle --out ~/vibeke-debug.tar.gz
The command prints the path, each file in the bundle, and what it leaves out. It works when no server runs and never starts one. Two options add more detail:
--include-pane <pane>adds the visible screen of a pane. Repeat it for more panes. This needs a running server.--include-scrollbackadds saved scrollback.
Add the Vibeke version from vibeke --version, your operating system and the steps that cause the problem. Report bugs at github.com/vibeke-ai/vibeke/issues.
Next steps
- Frequently asked questions for short answers about safety, platforms and updates.
- Process durability explains what survives a restart.
- Phone and browser access covers pairing, devices and recovery.