Troubleshooting & FAQ

Agent won't start

• Open the terminal and run the agent's CLI manually. If it fails there, it's an auth or install problem in the CLI itself — not DevAgent.
• Make sure the CLI is on the PATH DevAgent sees (check Settings → Agents).
• Try the Restart chip on the tab.

Diff view looks wrong / stuck

• Click the refresh icon on the diff toolbar — DevAgent re-reads the worktree.
• External git operations (rebase, reset) can land between refreshes.

Worktree creation fails

• The start-from ref may not be fetched. Open a terminal in the repo and run git fetch origin.
• The target directory may already have a worktree for that branch — delete it or pick a new branch name.

DevAgent CLI says "command not found"

Register the CLI under Settings → General → DevAgent CLI. On macOS it installs a shim into ~/.local/bin; make sure that's on your shell's PATH.

SSH connects but remote terminals fail

• Confirm the remote has Node and network access for the first-time relay install.
• On Linux, install a C/C++ toolchain if terminals never spawn: make, g++/clang++, python3 (see SSH worktrees).
• Reconnect after installing tools so DevAgent can reinstall native modules.

SSH works for files but not “Download Folder”

Folder download needs recursive SFTP transfer. File download may still work on system-SSH-only connections. Use a terminal tar/scp as a fallback.

“Open in VS Code” is disabled or Local only

• Use an SSH worktree (not a Remote DevAgent Server active runtime).
• Set the Open-in command to VS Code / Insiders, not Cursor or a multi-arg shell command.
• Refresh SSH targets if the host was removed.

Kerberos login fails

• Ensure klist shows a valid ticket for the host realm.
• Confirm GSSAPIAuthentication yes for that Host in OpenSSH config, then re-import or re-test the target in Settings → SSH.

Browser says browser_no_tab

No tab is open in the current worktree. Open one with devagent tab create --url ... or open the browser pane manually and navigate.

Performance & memory

• Close worktrees you're not actively using. Each worktree keeps file watchers alive.
• Split layouts with many browser tabs are the biggest RAM users — close browsers you don't need.

GitHub PR panel / checks / Tasks errors

Rate limits, bad gh auth, missing scopes, and repo access issues all show up in Source Control and the PR Checks panel. See Troubleshooting GitHub errors for the full matrix (including why GitHub API Budget in Settings can look fine while REST is still blocked).

Quick checks:

gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'

Logs

Help → Open Logs opens the directory with DevAgent's logs. Attach these when filing a bug.

Reporting issues

• Help → Send Feedback (in-app) — paste or drag screenshots into the dialog, or pick image files; thumbnails show before you submit. Attach logs when the bug is hard to reproduce.
• GitHub Issues — bugs and feature requests.
• Discord — real-time help.