Feature Proposal: Native /doctor and agy doctor diagnostic command

[josephsieh]

Feature Proposal: Native agy doctor Diagnostics Command

Status: Proposed / Under Review

Target: Google Antigravity CLI (agy) & IDE

Issue: #587

---

1. Overview

In modern developer-agent environments, troubleshooting environment setup, version mismatches, security keys, and workspace scale issues can consume substantial time.

By analyzing the capabilities of both Anthropic's official claude doctor and community extensions like millionco/claude-doctor, we propose a comprehensive, native /doctor command and CLI agy doctor subcommand for Google Antigravity.

This proposal incorporates a strict safety model for auto-remediation, cross-platform credentials analysis, and a structured implementation roadmap.

---

2. Capabilities Analysis & Mapping

Category	Claude Code doctor	Proposed agy doctor
Installation	Detects NPM vs binary paths & version conflicts.	Detects duplicate agy executable paths (e.g., /usr/local/bin vs ~/.local/bin).
Dependencies	Verifies ripgrep availability and path setups.	Verifies git, fd (per global GEMINI.md / AGENTS.md principles), and active pixi Python environments.
Configuration	Checks settings JSON syntax and resolves invalid parameters.	Validates syntax of ~/.gemini/antigravity-cli/settings.json.
Credentials	Verifies macOS Keychain / .credentials.json write access.	Checks Platform Keychain Matrix (macOS, Linux system keyring, Windows Credentials).
Daemon	Audits background process supervisor health.	Inspects local background agent daemon process status.
Network & SSL	Tests proxies (HTTPS_PROXY) and custom EXTRA_CA_CERTS.	Measures Google API connection latencies and verifies local proxy/certificate setups.
Watchers	Reports active environment watches.	Diagnoses system level watchers (e.g. sysctl limits) vs current workspace file count.
Behavior	N/A (requires community claude-doctor plugin).	Analyzes .system_generated/logs/transcript.jsonl for execution loop patterns.

---

3. Detailed Specifications

A. Auto-Repair & Remediations Safety Model

To prevent critical system configurations from being modified without user oversight, agy doctor implements a Conservative & Confirmed safety model:

1. Read-Only by Default: Running agy doctor simply reports health. It will never modify configuration or system files on its own.
2. Explicit Command Flag: Remediations must be explicitly requested using the command:

   agy doctor --auto-repair

3. Low-Risk Auto-Fixes: Safe actions (e.g., appending standard ignores to .gitignore) can run after a single interactive prompt confirmation.
4. Dry-Run Guidelines: Changes to settings templates or additions to GEMINI.md / AGENTS.md are printed to stdout as suggestions; they are never auto-committed to the workspace files.

B. Transcript Loop & Performance Analysis

To prevent performance degradation on large repositories:

• Log Size Boundary: Transcripts under .system_generated/logs/transcript.jsonl are only analyzed up to a max size of 2MB. If a log exceeds this size, the script processes only the last 1,000 steps.
• Loop Heuristics: Flags a warning if it detects 3 or more consecutive failures of the same tool or terminal command, indicating that the agent is trapped in an error loop. To reduce false positives, intentionally iterative retry loops (e.g., expected compiler warnings) are excluded based on distinct error outputs.

C. MCP Server Ping Protocol

To ensure the diagnostic run completes quickly even with unresponsive integrations:

• Timeout Handling: All MCP server initialization pings are hard-capped at a 5-second timeout.
• Fallback Behavior: If a server times out, it is immediately marked as [✗] Unresponsive in the report, and the doctor command continues to the next check without hanging.

D. Platform Keychain Credentials Matrix

The security diagnostics check credentials access based on the operating system:

• macOS: Checks access to the Secure Keychain Service. Checks for iCloud synchronization blocks on command line credentials.
• Linux: Detects libsecret or local credential storage fallbacks (pass).
• Windows: Verifies read/write access to the Windows Credential Manager.

E. Configurable Thresholds & Metrics

To accommodate different system capabilities and repository scales, warning thresholds are fully user-configurable.

• Configuration File: Users can define thresholds in a dedicated ~/.gemini/antigravity-cli/doctor.toml file.
• Metrics: Customizable settings include watcher_warning_ratio (e.g., warn when 80% of OS limit is reached), api_latency_warning_ms (default 500ms), and loop_detection_count (default 3).

---

4. Proposed User Interaction Design

$ agy doctor --verbose
=== Antigravity CLI Diagnostic Report ===

--- [1/4] Environment Diagnostics ---
[✓] Shell Path: /Users/joseph/.local/bin/agy
[✓] Settings JSON: Valid
[✗] Security Keychain: Writable (MacOS Keychain) - Access Denied on iCloud sync keychain items.
    -> Fix: Run `keychain-helper` to link local keys.
[✓] Supervisor Daemon: RUNNING (PID: 8421)
[!] File Watcher Limits: Worn (Workspace contains 12,410 files; OS watcher limit is 8,192).
    -> Suggestion: Increase sysctl watch limit. Run auto-fix to set.
[✓] Network Proxies: None defined. Connection latency to Vertex AI is 31ms.

--- [2/4] Integrations & MCP ---
[✓] MCP Servers (2 registered): Playwright MCP, Serena MCP
[✗] Custom Skills:
    - Skill "troubleshooting" is missing a valid SKILL.md metadata frontmatter block.

--- [3/4] Transcript Audit ---
[!] Session Behavior:
    - Warning: Found 3 command loops in session '6a891c7b' (repeated failed write commands).
    - Recommendation: Add permission rules to GEMINI.md.

Would you like to run interactive Auto-Repair? [Y/n]: 

---

5. Implementation Roadmap

We propose breaking this feature down into 4 milestones:

• Milestone 1: Diagnostics MVP (Read-Only)
  • Verify agy path, configuration file syntax.
  • Check system daemon process health.
  • Report test ping latencies to Vertex AI.
• Milestone 2: Security & Network Integration
  • Build the cross-platform Keychain credentials diagnostics matrix.
  • Inspect SSL certificates, firewalls, and custom CA cert environment setups.
• Milestone 3: Auto-Repair Scaffold
  • Introduce --auto-repair flag.
  • Add confirmation gates for low-risk fixes (e.g. .gitignore exclusions).
• Milestone 4: Transcript Loop Audits & Suggestion Engine
  • Parse conversation .jsonl transcript logs.
  • Generate dry-run guideline suggestions for GEMINI.md / AGENTS.md based on repeated failures.