GitGhost Desktop

GitGhost Desktop gives one local coding-agent task a shared, reviewable result. Start with a repository and the agent you already use; GitGhost records the session, changed files, checkpoints, and policy decisions. The deeper file, terminal, preview, observability, and governance tools remain available after that first path is clear.

Use it when you want agents to work against files on your computer while GitGhost remains the shared project, policy, evidence, and review layer.

What The Desktop App Does

Area	What You Can Do
Projects	Open a local Git checkout or select a GitGhost repository. Keep several repositories open as tabs.
Conversations	Run supported coding agents, choose available models and modes, stream replies and tools, answer permission requests, and continue a conversation.
Native terminals	Run installed vendor CLIs with their normal interactive interface and authentication. Open several agents in separate checkouts when they need to write concurrently.
Code	Browse the repository tree, inspect Git status, open text files in Monaco, compare with HEAD, edit, and save with changed-on-disk protection.
Preview	Open local web applications or HTTPS pages in an isolated browser panel. Inspect Android emulators and iOS simulators from the same conversation.
Git	Review selected changes, commit selected files, fetch, fast-forward pull, and push committed history.
Evidence	Review captured sessions, checkpoints, files touched, action plans, approvals, and execution records.
Governance	Inspect effective project policy and send scans or other governed requests through GitGhost rather than silently bypassing policy.

The Main Navigation

View	Purpose
Dashboard	Open or resume a project, recover recent working folders from supported local coding agents, and see the shortest path from account to repository to agent.
Conversations	Work with structured agents and import or automatically follow supported CLI sessions.
Terminal	Run vendor-native agent CLIs or standalone terminal sessions.
Observability	Follow active and completed agent runs, deterministic findings, usage reported by providers, and private terminal lifecycles across one project or every workspace.
Sessions	Review GitGhost-captured session evidence and checkpoints.
Files	Browse, compare, edit, and save repository files.
Actions	Track governed plans, approval state, and execution evidence.
Agents	Detect local agent runtimes, inspect setup, launch an agent, and enable project-scoped capture where supported.

Before a workspace is open, the app shows only Dashboard so the first choice is clear. After a repository opens, the workspace views above become available. The right-side conversation inspector provides Code, Browser, Mobile, Activity, and Review without leaving the conversation.

Recover Recent Agent Work

Recent agent work on the Dashboard identifies working directories from bounded local metadata for Codex, Claude Code, Gemini CLI, Cursor, OpenCode, and GitHub Copilot. It groups matching agents by exact folder and keeps nested monorepo paths intact. When several providers share one folder, their logos stay in a fixed multi-row identity grid beside the workspace name instead of covering its name or path. Claude discovery reconciles its direct session metadata, global history index, and project registry. Gemini uses its project and chat index, Cursor uses local ACP session metadata plus its remembered-project registry, and OpenCode uses its local session database. Copilot uses its current workspace-state records and adds numeric usage from its local database when present.

Select Open to register a discovered Git checkout, or View when it is already open. Hide removes an entry until newer agent activity appears there. Use Pause when you do not want the desktop to read either local index. Large histories show ten folders per page with the current visible range. The header and page controls remain visible at normal laptop window heights while the folder rows scroll inside the panel. You do not need to maximize the application to reach pagination: GitGhost sizes the panel from the available window height and keeps the bottom status bar outside that scroll area.

A moved or deleted historical folder remains in the list with an unavailable label and a disabled Open button. This makes stale history explainable without guessing that the provider never recorded it.

This recovery list retains only local session identifiers, working directories, agent names, activity times, and numeric usage classes when OpenCode or Copilot reports them. It does not retain history titles, summaries, prompts, pasted content, transcript messages, commands, tool arguments, results, or logs. It also does not search the disk, call a provider network service, install hooks, connect a GitGhost project, or upload discovered paths. A folder outside a Git repository can be listed for orientation but cannot bypass normal repository registration.

Observe Agent Runs

Observability brings structured conversations, imported sessions, and native agent terminal lifecycles into a local operational workspace. Its category rail separates overview charts, runs, tools, failures, findings, and capture coverage.

Select a run to inspect its duration, messages, tools, approvals, reported model, validated usage when available, deterministic findings, and bounded timeline. Token usage separates uncached input, cache reads, cache writes, output, and reasoning counts while preserving the provider's authoritative total. Terminal contents remain private and are never stored in the ledger. See Agent Observability for capture levels and limits.

Supported Desktop Packages

Operating System	Current Preview Package	Important Requirement
macOS Apple Silicon	DMG	macOS 13 or later. The preview is ad-hoc signed and not Apple-notarized, so installation remains user-confirmed.
Windows x64	EXE installer	Git for Windows and Git Credential Manager are required for secure private-repository cloning. The preview does not yet have an Authenticode publisher signature.
Linux x64	AppImage or DEB	Git and an unlocked Secret Service keyring are required. AppImage supports verified automatic replacement and rollback; DEB updates remain system-package installs.

Visit gitghost.ai from the computer where you want to install the app. The download control selects the compatible package and requires your GitGhost account before serving the private installer.

Understand The Trust Boundary

GitGhost Desktop coordinates local tools; it is not an operating-system sandbox.

• Native agent terminals run as your local user and keep the vendor's own permissions and authentication.
• Local permission prompts control one desktop agent request. They are not GitGhost cloud approvals.
• Project Agent Policy remains authoritative for capture, risk classes, scans, action requests, and cloud execution.
• Opening a folder never commits, pushes, installs capture hooks, or changes repository visibility automatically.
• Recent agent work reads bounded local metadata only and never registers a discovered folder automatically.
• Connecting one checkout to GitGhost creates project-scoped access. It does not give every local repository access to that project.
• The renderer never receives account tokens or arbitrary Electron/file-system access.

First Successful Workflow

1. Install and sign in.
2. Open or connect one repository.
3. Start one small task with an installed agent.
4. Open the captured result and review the session, changed files, checkpoints, and policy decisions.

That is the complete first-use path. After it works, use code and Git review, agent observability, web or mobile preview, and governed actions as the task requires.

What Success Looks Like

A healthy setup has all of these signals:

• The status bar shows Connected.
• The selected local folder stays visible as the workspace, including when it is nested inside a larger Git repository.
• The Agents view reports the intended vendor runtime as detected and its setup check passes.
• A conversation can stream a reply or open the vendor-native terminal.
• GitGhost project linkage appears in Review.
• Captured work appears in Sessions only after capture is enabled and policy allows it.
• Push remains disabled until there are committed local changes and a valid Git credential.

Continue with Install GitGhost Desktop.