Desktop Troubleshooting
Start with the visible error, then identify whether it belongs to GitGhost authentication, a coding-agent vendor, the local operating system, Git, or project policy. Avoid deleting a checkout, keyring entry, or worktree until its files and ownership are understood.
Installation And Updates
No Newer Version Is Available For This Computer
- Compare the installed version and channel in Settings > Updates.
- Confirm that a compatible package exists for the operating system and architecture.
- Confirm that the account is still signed in.
- Retry after 30 seconds if a manual check just ran.
- Remember that stable clients do not install preview releases automatically.
The current ad-hoc-signed macOS preview can verify and download an update but still requires a user-confirmed replacement. Fully automatic replacement starts with a future Developer ID-signed and notarized stable build.
The Download Opens A Private GitHub 404
Use the download control on gitghost.ai, not a private source-repository URL. Sign in when prompted so GitGhost can serve the first-party installer.
Projects And Files
The App Opens The Repository Root Instead Of My Nested Project
Install desktop 0.10.1 or later. If the shortcut was created by 0.10.0, remove that incorrect shortcut once and reopen the exact nested folder. New shortcuts preserve the selected workspace while keeping the enclosing Git root for repository operations.
CLI Output Exceeded The Safety Limit
Install desktop 0.10.1 or later. That release streams large repository listings and caps the explorer at 5,000 safe entries instead of treating the total Git output as one protocol message. A visible truncation notice means the cap was reached; it does not mean the repository failed to open.
A File Will Not Open Or Save
Check whether the file is binary, oversized, ignored, sensitive, linked outside the workspace, deleted, or changed on disk while you had unsaved edits. GitGhost intentionally restricts these cases rather than silently overwriting data.
Agents And Session Synchronization
CLI Sync: Agent Returned An Invalid Protocol Message
Update to desktop 0.10.1 or later, restart the app, and run Check setup for the agent. The patched protocol reader ignores bounded plain-text startup diagnostics while still rejecting malformed JSON, oversized messages, and excessive diagnostic output.
If the error remains, open the vendor-native terminal and verify that the installed agent starts normally. Do not paste credentials or complete transcripts into a support report.
CLI Sync: Agent Connection Closed
Check the agent process, vendor authentication, and desktop version. A large Codex history on an older desktop could cross the previous connection limit and hide the actual cause behind this message. Current versions request bounded recent pages and preserve already displayed messages when refresh fails.
A New Codex CLI Session Does Not Appear
- Confirm that the session working directory exactly matches the open workspace.
- Bring GitGhost Desktop into focus and wait for the refresh.
- Check that discovery is not paused for that workspace.
- Finish any active external Codex turn before trying to continue the same session in the desktop.
- Use the existing-session picker for an older session outside the recent discovery window.
Automatic native-history discovery currently applies to Codex only.
An Agent Is Unavailable
Open Agents, select Check setup, and use the reported fix. Installation and authentication are separate checks.
| Agent | Common Requirement |
|---|---|
| Codex | A supported Codex CLI and valid OpenAI sign-in. Do not select a model name that the account does not support. |
| Claude Code | Sign in through the native CLI for terminal use. Structured Claude Agent SDK chat can require a separate API credential. |
| Gemini CLI | Use a current supported client and an eligible Google account. A vendor message that a client is no longer supported cannot be bypassed by GitGhost. |
| Cursor | Open its native terminal and complete Cursor sign-in, then retry the setup check. |
| OpenCode | Confirm the runtime and its chosen provider credential. |
| Copilot CLI | Confirm GitHub authentication and the account's Copilot entitlement. |
Sessions Or Evidence Do Not Appear In GitGhost
Confirm the project link, capture toggle, agent setup, and effective Agent Policy. Start a new session after enabling capture. A native terminal does not automatically become a captured structured transcript.
Browser And Mobile Preview
Android SDK Platform Tools Were Not Found
Android Studio alone is not enough. Open Tools > SDK Manager > SDK Tools, install Android SDK Platform-Tools, apply the change, and restart GitGhost. Then start an emulator and confirm it appears in adb devices.
No iOS Simulator Is Available
iOS preview requires macOS, Xcode, an installed Simulator runtime, and Xcode command-line tools. Open Xcode's platform settings to install a runtime, then open Simulator or refresh the device list.
A Website Does Not Load In The Embedded Browser
Confirm the URL and local server first. Some external sites block embedding or require popups, extensions, downloads, or permissions that the isolated preview rejects. Use Open externally for those sites.
Policy And Permissions
Project Agent Policy Disables This Tool Risk Class
The project's effective Agent Policy denied the requested operation. Ask a project administrator to review the relevant risk class and approval rule in Project Settings. Do not repeatedly retry or use a native terminal to bypass an intentional project control.
Local Permission Was Allowed But The Cloud Action Is Blocked
Local permission and GitGhost approval are separate. Review Actions for the project policy decision, risk class, approval requirement, and execution state.
Git And Repository Access
Current Token Does Not Have Required Scope: repo:write
Update the desktop, sign out and back in if requested, then reconnect the project or refresh its scoped Git access. Confirm that your account can administer or write to the intended project. Do not replace the project-scoped credential with a token embedded in the clone URL.
Git Cannot Read A Username Or Password
Open Review and select Configure Git access. On Windows, confirm Git Credential Manager is installed. On macOS, allow the approved Keychain operation. Keep the remote in this form:
https://gitghost.ai/git/<owner>/<project>.git
Pull Or Push Is Disabled
Fetch first. Pull is available only for a safe fast-forward. Push needs committed local history, a valid remote, and a stored credential. Resolve diverged history explicitly in your normal Git workflow.
Collect Safe Support Information
Open Settings > Support and collect only the bounded diagnostics needed for the problem:
- desktop version, channel, operating system, and architecture;
- agent name and setup-check result;
- project connection state without its credential;
- the exact error and approximate time; and
- whether the same operation succeeds in the vendor-native terminal.
Remove tokens, passwords, API keys, complete transcripts, private source, and personal filesystem paths before sharing a report.
Return to the GitGhost Desktop overview or review Support And Troubleshooting.