Agent Observability

The Observability workspace shows what local coding agents are doing across your open projects. Use it to compare outcomes and latency, inspect a specific run, find tool failures, review deterministic findings, and understand which evidence GitGhost actually received.

Open Agent Observability

Select Observability in the desktop navigation.

• Open it from the Dashboard to see runs across every registered local workspace.
• Open a repository first to limit the ledger to that workspace.
• Keep the view open while an agent works. Structured events refresh as they arrive, and the view also checks for changes periodically.

The detailed workspace is local to this computer. For a connected project, the desktop also synchronizes bounded operational metadata to the web Agent Control Room. This is different from Sessions, which shows governed Agent Protocol evidence.

The category rail separates routine monitoring from investigation:

Category	Use It For
Overview	Outcomes, agent health, capture coverage, first-response latency, provider-reported tokens, and current run state.
Runs	Search, filter, and inspect one structured or lifecycle run.
Tools	Compare tool categories, calls, failures, measured latency, and the agents using each tool.
Failures	Find failed runs, failed tool events, and runs that need attention.
Findings	Review explainable stall, loop, failure, and approval-wait rules.
Coverage	See which agents and capture sources supplied evidence and review the cloud-sync boundary.

Read The Summary

The top strip gives a quick operational count:

Metric	Meaning
Active now	Managed conversations or agent terminals that are working or waiting.
Need attention	Runs with a warning or critical deterministic finding.
Tool calls	Calls reported by structured agent runs. The Tools category separately shows how many detailed events were retained.
Median first response	The median time from a managed prompt to its first structured assistant response. Terminal-only runs are not included.
Measured tokens	The authoritative validated total supplied by the provider, or a compatible derived total for older records. A dash means no provider supplied usage.

Open Runs to see the coverage row. Select an agent chip to filter the run list; select it again to return to all agents.

Read The Operations Overview

The Overview category combines six operational views:

• Run outcomes stacks completed, active, failed, and stopped runs over the last seven days.
• Agent health compares run count, terminal success, average duration, tool calls, and runs needing attention. Select an agent row to filter the ledger.
• Capture coverage separates structured chat, imported session, and terminal lifecycle data. Select a source to filter the ledger.
• First response latency compares daily averages for runs with a measured first structured response.
• Token usage separates uncached input, cache reads, cache writes, and output. Reasoning is shown as a count within output rather than added twice.
• Current state groups working, waiting, completed, failed, and stopped runs.

These values come from recorded runs. GitGhost does not create sample activity when the ledger is empty.

Check Cloud Sync

The indicator beside Refresh reports one of four states:

State	Meaning
Local only	No workspace in this view is connected to a GitGhost project.
Syncing with GitGhost	Connected activity is waiting for its next bounded upload.
Synced to GitGhost	The latest changed run metadata was accepted by GitGhost.
Sync needs attention	Authentication, project connection, network, or client compatibility prevented the last upload.

Sync runs after agent activity and retries periodically while the desktop is open. A parallel checkout keeps its own receipt even when another checkout is connected to the same project.

Inspect Runs

Use the controls above the run list:

1. Search by conversation title, workspace, path, agent, or model.
2. Filter by Active, Needs attention, Failed, or Completed.
3. Filter the capture source:
   • Structured chat for conversations managed by GitGhost Desktop;
   • Imported sessions for supported provider history you explicitly opened;
   • Terminal lifecycle for native agent start and exit records.
4. Select a run to inspect it.

The selected run shows duration, displayed-message count, reported tool count, approval count, provider model when known, findings, and a chronological event timeline.

Investigate Tools And Failures

Open Tools to compare reported calls with detailed captured events. A run can report a total tool count even when its provider did not supply one event envelope per call, so GitGhost keeps those numbers separate rather than inventing details. The tool table shows category, captured calls and failures, average and slowest measured duration, and observed agents.

Desktop 0.15.1 and later also indexes privacy-safe tool metadata from recent native Codex and Claude Code sessions. This includes the tool name or normalized category, completion state, timestamp, and measured duration when the provider recorded one. Large histories use a bounded latest-event window; Reported calls can therefore be higher than Captured events. The notice above the charts explains this difference.

Open Failures to compare failed runs, captured failed tool events, runs needing attention, and critical finding types. Select an affected run to open its complete bounded timeline under Runs.

Understand Findings

Findings use fixed, explainable rules. They do not ask another model to judge the agent and do not change its permissions.

Finding	When It Appears
No recent activity	An active structured run has emitted no event for at least five minutes.
Long-running turn	A turn remains active for at least twenty minutes.
Approval is waiting	A local permission request has waited for at least five minutes.
Tool repeated	The same tool title appears three or more times in one run.
Repeated tool failures	Two or more structured tool calls report failure.
Possible tool loop	The latest tool sequence repeatedly alternates between the same two actions.
Run failed	The provider process ends with an error.

A finding is a prompt to inspect the timeline. For example, repeated test failures may be expected while an agent fixes a defect, while alternating identical actions with no file progress can indicate a loop.

Know What Each Agent Exposes

Work Source	What The Ledger Can Show
Structured Claude Code, Codex, Gemini, Cursor, OpenCode, or Copilot conversation	Per-turn status, model when reported, displayed messages, tools, approvals, duration, error, and validated usage when available.
Imported or discovered Codex session	Tool type, completion state, failure count, duration, and numeric usage are recovered automatically from bounded local rollout metadata. Displayed conversation text still requires an explicit import.
Discovered Claude Code session	Tool name, completion or failure state, duration, numeric usage when available, and exact working-folder metadata. Transcript text and tool input or output are not retained.
Discovered Gemini CLI or Cursor session	Session identity, activity time, and exact working-folder metadata from the provider's bounded local index. Cursor's remembered project registry may identify a folder without claiming a recoverable session. Conversation and tool content are not imported.
Discovered OpenCode or Copilot session	Session identity, activity time, and exact working-folder metadata. Numeric input, cache, output, and reasoning usage appears only when the local provider database reports it; Copilot workspace-state-only records remain unmeasured. Titles, summaries, events, and transcripts are not imported.
Native agent terminal	Start, exit, status, model, permission mode, duration, and exit code only.
Folder discovered on the Dashboard	Folder and session metadata plus privacy-safe tool and numeric usage metadata when available. It does not become a ledger transcript until you explicitly open or import supported history.

Usage is not available from every provider protocol. GitGhost displays not reported instead of treating missing usage as zero or estimating a cost.

The categories are normalized because providers report caches differently:

• Codex/OpenAI input already contains cached input. GitGhost subtracts the cache categories only for the visual uncached-input value and does not add them to the total again.
• Claude reports input, cache read, and cache creation as additive categories.
• Reasoning output is part of output. GitGhost displays the count for visibility but does not add it as another segment.

These are numeric counters. GitGhost does not read or synchronize hidden reasoning text.

Privacy Boundary

GitGhost Desktop does not store native terminal contents in the ledger. It also does not add credentials, environment variables, hidden reasoning, or arbitrary process diagnostics to observability records.

Structured event text is the same bounded, redacted display history used by the local conversation view. Native-session indexing retains only tool identity/category, status, timestamps, duration, counts, and numeric usage. It discards prompt and response text, command bodies, arguments, tool output, diffs, local paths, credentials, and hidden reasoning. Terminal output remains memory-only and disappears when the app closes. The ledger cannot run commands, grant an approval, or override project Agent Policy.

Cloud synchronization is narrower than the local ledger. It includes opaque IDs, agent and model identifiers, status, timings, counts, provider-reported token totals, fixed event classes, failure classes, and finding codes. It excludes prompts, responses, commands, diffs, paths, environment variables, credentials, and terminal output.

If A Run Is Missing

1. Confirm you opened Observability for the correct repository, or return to the Dashboard for the all-workspace view.
2. Clear agent, state, source, and search filters.
3. Wait up to fifteen seconds for supported local agent metadata to be indexed, then select Refresh. Periodic connected-project sync also refreshes the index while the desktop remains open.
4. For a native terminal, confirm it was opened from GitGhost Desktop. External terminal contents are never captured.
5. For Codex conversation text, open or import the matching exact-workspace session. Tool and usage metadata do not require transcript import on desktop 0.15.1 or later.
6. For cloud evidence, use Sessions and confirm project capture and Agent Policy are enabled.

For cross-project charts, tool percentiles, and grouped failures, continue with the Agent Control Room.

Continue with Coding Agents And Conversations or Governance, Sessions, And Actions.