Troubleshooting

The QR code contains a provisioning token for secure pairing. If scanning fails:

1. Ensure you're signed in to the iOS app with GitHub or Google first
2. Check that the plugin is running - look for the Kibbler tool window in your IDE
3. Provisioning tokens expire after 10 minutes - try clicking "Regenerate QR Code"
4. Make sure your phone has internet access (provisioning goes through our tunnel server)
5. Check the plugin logs for errors (View > Tool Windows > Kibbler)

During pairing, your phone generates its own encryption keys locally. The private key never leaves your device.

If issues persist, click "Reset All Certificates" in the plugin settings to clear all stored certificates and start fresh. You'll need to re-pair all devices afterward.

The tunnel uses a persistent WebSocket connection from your desktop to our server. Disconnections can be caused by:

• Network instability: Check your internet connection on your desktop
• Computer sleep: The tunnel disconnects when your computer sleeps - it will reconnect on wake
• IDE restart: The tunnel agent runs within the plugin and restarts with the IDE
• Firewall/proxy: Some corporate firewalls block long-lived WebSocket connections

Your phone connects to {subdomain}.tunnel.kibbler.dev where the subdomain is derived from your certificate. Both ends will automatically reconnect.

This error typically means the proxy server isn't reachable:

1. Verify the IDE plugin is installed and enabled
2. Check that the proxy server started - look for "Proxy server started" in the plugin logs
3. On macOS, check System Preferences > Security & Privacy > Firewall for blocked connections
4. On Windows, check Windows Defender Firewall settings
5. Try restarting your IDE

Kibbler uses mTLS certificates for secure authentication. Certificate issues may occur if:

• Certificate expired: Certificates are valid for 1 year. The app will prompt you to renew within 30 days of expiry.
• Certificate revoked: Check the Devices tab in the iOS app - you may have revoked this desktop.
• Keychain corrupted: On iOS, try deleting and reinstalling the app to clear stored certificates.
• Plugin data cleared: If plugin certificates were deleted, you'll need to re-pair your phone.

To re-pair: open the Devices tab in the iOS app, remove the old desktop, and scan a new QR code from the plugin.

Plugin installation issues are often version-related:

• Kibbler requires IDE version 2023.2 or later
• Update your IDE: Help > Check for Updates
• If installing manually, ensure you downloaded the correct version
• Try installing from the JetBrains Marketplace directly within your IDE (Settings > Plugins > Marketplace)

The Kibbler tool window should appear in your IDE's sidebar:

1. Go to View > Tool Windows > Kibbler
2. If not listed, check Settings > Plugins and ensure Kibbler is enabled
3. Try restarting your IDE after enabling the plugin
4. Check that you have a project open (the plugin requires an active project)

If the plugin is causing IDE instability:

1. Update to the latest plugin version (Settings > Plugins > Updates)
2. Clear IDE caches: File > Invalidate Caches and Restart
3. Check for conflicting plugins - try disabling other plugins temporarily
4. Increase IDE memory: Help > Change Memory Settings

Please report crashes with your IDE logs (Help > Collect Logs and Diagnostic Data).

The proxy server runs locally and may fail to start if:

• Port already in use: Another application is using port 31415. Check plugin settings to change the port.
• Binary not found: The proxy binary may not have been extracted. Try reinstalling the plugin.
• Permission denied: On macOS/Linux, the binary may need execute permissions.
• Certificate generation failed: The plugin generates a local CA for E2E encryption. Check disk space and write permissions.

Certificates are stored in the plugin's data directory and are cleaned up when you uninstall the plugin.

The plugin needs to register with the tunnel server before showing a QR code:

1. Check your internet connection - the plugin needs to reach tunnel.kibbler.dev
2. Ensure a project is open in your IDE
3. Look for error messages in the Kibbler tool window
4. Try clicking "Refresh" or closing and reopening the Kibbler panel

The plugin generates a local Certificate Authority (CA) to sign certificates for E2E encryption. This happens automatically on first setup.

Windows Defender SmartScreen or antivirus software may block the Kibbler proxy binary:

1. When you see "Windows protected your PC", click More info then Run anyway
2. If blocked by real-time protection, open Windows Security > Virus & threat protection > Protection history
3. Find the blocked item and select Allow on device
4. To add an exclusion: Windows Security > Virus & threat protection > Manage settings > Add or remove exclusions
5. Add the plugin's data directory: %APPDATA%\JetBrains\<IDE>\plugins\kibbler

Third-party antivirus (Norton, McAfee, Kaspersky, etc.) may also flag the proxy - check your AV quarantine and add similar exclusions.

macOS may prevent the proxy binary from running due to security restrictions:

1. If you see "cannot be opened because the developer cannot be verified":
2. Open System Settings > Privacy & Security
3. Scroll down to the Security section where you'll see a message about the blocked app
4. Click Open Anyway and confirm with your password
5. Restart your IDE and try again

You only need to allow the binary once. macOS remembers your choice for future launches.

Local or corporate firewalls may block Kibbler's network connections:

• macOS: When prompted "Do you want the application to accept incoming network connections?", click Allow. If denied, go to System Settings > Network > Firewall > Options and allow kibbler-proxy.
• Windows: Check Windows Security > Firewall & network protection > Advanced settings > Inbound Rules for blocked connections. Create a rule to allow the proxy if needed.
• Corporate networks: Ask IT to whitelist outbound HTTPS (port 443) to *.tunnel.kibbler.dev and allow WebSocket connections.

The default proxy port is 31415 (configurable). The tunnel uses WebSocket over TLS which some corporate proxies may block.

VPN software can interfere with Kibbler's tunnel connection:

• Split tunneling: If your VPN supports it, exclude tunnel.kibbler.dev from the VPN tunnel
• DNS issues: Some VPNs override DNS settings - try using 8.8.8.8 or 1.1.1.1 manually
• Connection drops: VPN reconnections may temporarily disrupt the tunnel - it should reconnect automatically
• Corporate VPN: Some corporate VPNs block all non-approved traffic - contact IT for assistance

The tunnel connection is already encrypted with TLS 1.3, so a VPN provides no additional security benefit for Kibbler traffic.

If the app crashes immediately after opening:

1. Force quit the app and reopen
2. Restart your iPhone
3. Ensure you're on iOS 17.0 or later
4. Delete and reinstall the app from the App Store
5. Check available storage - the app needs at least 100MB free

Kibbler uses OAuth sign-in via your phone (you only need to sign in once):

• Make sure you have internet access and Safari can open
• If the Safari page doesn't redirect back to the app, try again
• Check that you've authorized the Kibbler app in your GitHub/Google account settings
• Try signing out and signing in again if your session seems stuck

Your auth token is stored securely in the iOS Keychain and lasts 30 days.

If sessions aren't appearing in the app:

• Pull down to refresh the session list
• Check the connection status indicator at the top
• Ensure your computer is awake and the IDE is running
• Verify the tunnel is connected in the plugin's Kibbler panel
• Check the "Desktop" tab to see sessions from Claude Code CLI on your machine

Desktop sessions show conversations from ~/.claude/projects/ - you can continue any desktop Claude conversation from your phone.

Camera access is required for pairing and vision features:

1. Open iPhone Settings > Privacy & Security > Camera
2. Ensure Kibbler is listed and enabled
3. If not listed, delete and reinstall the app (this resets permissions)
4. Try restarting your iPhone if the camera appears frozen

If you can't see pending changes to approve:

• Check that approval mode is enabled in the plugin settings
• Ensure Claude has actually made changes (check the conversation)
• Pull down to refresh the pending changes list
• Large diffs may take a moment to render - wait a few seconds

Kibbler requires Claude Code CLI to be installed:

1. Install Claude Code: npm install -g @anthropic-ai/claude-code
2. Verify installation: claude --version
3. If installed but not found, check your PATH settings
4. The plugin looks for claude in standard locations

You can also set a custom Claude CLI path in the plugin settings.

Response times depend on multiple factors:

• Large codebases: Claude needs to analyze context - this takes longer on big projects
• API load: Anthropic's API may be experiencing high demand
• Complex requests: Multi-file edits and analysis take more time
• Network latency: Check your internet connection speed

The app shows a streaming indicator while Claude is working. Timeout is set to 5 minutes by default.

Kibbler uses your existing Claude Code authentication:

1. Make sure Claude Code is authenticated: run claude in terminal
2. If prompted, log in with your Anthropic account
3. Verify your subscription is active at console.anthropic.com
4. Try running claude --logout then log in again

Kibbler doesn't store or manage your API key - it uses Claude Code's existing auth.

If Claude seems to "forget" previous conversation:

• Make sure you're continuing an existing session, not starting a new one
• Sessions are stored in ~/.claude/projects/ as JSONL files - don't clear this directory
• Very long sessions may hit token limits - start a new session and summarize context
• Check that the working directory matches between sessions

Kibbler uses the --resume flag to continue existing Claude conversations. Desktop sessions sync automatically.

You can browse and continue Claude CLI conversations from VS Code, terminal, or JetBrains:

• Open the "Desktop" tab in the session picker
• Only sessions from the last 7 days with messages are shown
• The session must be in the project directory the plugin is connected to
• Agent/subagent sessions are filtered out (only main conversations shown)

Desktop sessions are ephemeral on mobile - they stay on your desktop, and the phone just continues the conversation.