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

1. Compare the installed version and channel in Settings > Updates.
2. Confirm that a compatible package exists for the operating system and architecture.
3. Confirm that the account is still signed in.
4. Retry after 30 seconds if a manual check just ran.
5. Remember that stable clients do not install preview releases automatically.

The current ad-hoc-signed macOS preview and unsigned Windows preview can verify and download an update but cannot replace themselves automatically. Automatic replacement requires a Developer ID-signed and notarized app in /Applications/GitGhost.app, an Authenticode-signed Windows installation, or a writable Linux AppImage.

Update Now Still Shows A Manual Installer

Open Settings > Updates and read the compatibility reason below the available version.

• On macOS, quit copies running from a mounted DMG or Downloads, install the canonical app at /Applications/GitGhost.app, and use a production-signed build. Do not rename the app bundle.
• On Windows, automatic replacement stays disabled when the installed executable has no valid configured publisher signature.
• On Linux, automatic replacement applies to AppImage installations. DEB packages continue through the operating-system package manager.

GitGhost intentionally falls back to a verified installer rather than weakening these checks.

After the canonical Applications copy starts, GitGhost cleans legacy installer volumes that came from its own private update cache. A manually downloaded DMG remains yours to remove, and a currently running installer volume is left mounted so the app is never terminated unexpectedly.

An Automatic Update Fails

1. Keep the current app open and select Retry in the update prompt or Settings > Updates.
2. Confirm the selected Stable or Preview channel is the intended one.
3. Confirm the app location is writable and, on macOS, exactly /Applications/GitGhost.app.
4. If verification fails, do not reuse the downloaded file. Let GitGhost request a fresh artifact.
5. If automatic installation remains unavailable, use Show verified installer as the manual fallback.

A failed download, digest check, publisher check, or installer launch does not replace the working app. On Linux, GitGhost keeps the previous AppImage through the startup health window and rolls back if the new process exits early.

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

A Recent Agent Folder Does Not Appear

1. Open Dashboard and select refresh in Recent agent work.
2. Confirm discovery is not paused.
3. Confirm the agent session recorded an existing absolute working directory.
4. Start or resume one turn from that folder, then return to the Dashboard.
5. Move through the list pages when more than ten folders were discovered.
6. If the folder was hidden, newer agent activity makes it eligible to appear again.

GitGhost reads the providers' bounded local indexes rather than searching the computer. Deleted or moved historical folders remain visible with an unavailable label, but Open stays disabled. A folder that exists but is not inside a Git repository also remains visible for orientation and cannot be opened as a repository.

For Claude Code, current versions reconcile direct session metadata, the global local history index, and Claude's local project registry. The reader ignores display text, prompts, pasted content, transcript bodies, and malformed or relative paths. This improves older-folder coverage without importing the conversation.

Gemini CLI requires a local project root and session index. Cursor discovery covers local ACP sessions and remembered project directories; its interactive account-backed history selector is not imported. OpenCode requires its local session database. Copilot can use current workspace-state records and augments them with numeric database usage when present. If a source is not installed or has no local metadata, it is reported as unavailable rather than inventing a folder.

Dashboard folder recovery and transcript synchronization are separate. Claude Code folder metadata can appear even though automatic Claude transcript import is not supported.

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 transcript synchronization currently applies to Codex only. Other providers can still contribute folder/session metadata, and OpenCode or Copilot can contribute numeric usage when their local database reports it.

A Run Does Not Appear In Observability

1. Confirm whether Observability is filtered to one repository or showing all workspaces.
2. Clear the search, state, source, and agent filters.
3. For a native terminal, confirm it was launched from GitGhost Desktop. External terminal output is not imported.
4. For an existing Codex session, explicitly open or import the exact-workspace session.
5. Use Sessions instead when you are looking for platform-captured evidence rather than local desktop activity.

Tool Behavior Shows No Calls For A Native Session

1. Update to GitGhost Desktop 0.15.1 or later. Earlier versions could fall back to message-only Codex history when one large tool result crossed the protocol limit.
2. Keep automatic workspace discovery enabled on the Dashboard.
3. Wait up to fifteen seconds, open Observability > Tools, and select Refresh.
4. Clear agent, source, and workspace filters. Native Codex and Claude Code activity is listed as Imported sessions even when you did not import conversation text.
5. Compare Reported calls with Captured events. Large local histories keep a bounded latest-event timeline, so these values can differ without losing the total call count available in the scanned window.

GitGhost retains only tool identity/category, state, timing, counts, and numeric usage from native session records. It does not retain prompts, responses, commands, arguments, outputs, diffs, local paths, credentials, or hidden reasoning.

Missing provider usage is expected for adapters whose protocol does not report it. GitGhost does not invent token or cost values. When a provider reports usage, inspect Token usage for uncached input, cache read, cache write, output, and reasoning. Reasoning is included in output; it is not added to the total twice.

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.