Troubleshooting

An agent event never appears

1. Confirm back2vibing is enabled from the menu bar.
2. Open Agents. The agent should show Active, not Needs setup.
3. Run the repair action if one is offered.
4. Quit the old agent session, start a new one, and retry a short prompt.

Existing sessions do not always pick up a newly installed or repaired hook.

The event appears, but focus does not move

• Open Focus and confirm the action is not Notify me.
• Confirm back2vibing is enabled under System Settings > Privacy & Security > Accessibility.
• Check whether Disable during screen share is active in General.
• Check Supported Agents and Apps to see whether the surface supports exact return or only whole-window return.

The Session Dock does not appear

• Confirm at least one live session exists in Sessions > Active.
• Move the pointer to the top edge of the screen.
• Open Keyboard and use the configured Session Dock shortcut.
• Open Dock to check launch and workspace settings.

Sounds or all behavior are off

• Mute sounds disables audio only.
• Disable back2vibing disables focus changes and audio.
• Screen-share protection disables both while a share or recording is detected.

Sync & Test is blocked

Read the blocker in the dialog before changing repository state.

• Complete or abort an in-progress merge or rebase.
• Check out the intended Home Repo branch if it is detached.
• Move unsupported untracked paths out of the way.
• Stop the current Sync & Test target before starting another if switching is unavailable.

Do not use overwrite sync merely to bypass a blocker.

SSH does not connect

1. Run ssh <host> in a normal terminal and accept the host key.
2. Confirm that login succeeds without back2vibing.
3. Reconnect the saved host in SSH Remote.
4. Start a new remote agent session after the connection is active.

Still stuck

Open the app logs and share the smallest reproducible case in Discord. Include the agent, working surface, expected return target, and the first relevant error.