Document Antigravity data sources when the app is closed

[Yuxin-Qiao]

Summary

• Explain the agy CLI install/login prerequisite (brew install --cask antigravity-cli, ANTIGRAVITY_CLI_PATH override) for using the Antigravity provider without keeping the desktop app open.
• Add a "When the Antigravity app is closed" section covering the app -> agy CLI -> IDE -> OAuth fallback behavior, the all-100% OAuth placeholder, and the brief cold-start keyring/auth wait on the first refresh.
• Fix stale provider lists: README said "no external auth" and providers.md omitted the agy CLI HTTPS and Google OAuth sources.

Evidence behind the doc changes

All statements were verified live on 2026-08-05 with Antigravity.app open and closed on the same Mac (account email redacted below):

• App closed, agy installed and signed in: swift run CodexBarCLI usage --provider antigravity --verbose returns the cli source with real quota rows, e.g. Gemini Models: 2% left + Resets tomorrow, 11:52 AM, Claude and GPT: 100% left + reset time.
• App closed, no signed-in agy: the same command falls back to OAuth and shows only an all-100% availability row with no reset times.
• App open: the same command returns the app source. Fixed-schedule quota fields are byte-identical to the cli source (Gemini weekly usedPercent 97.8170183, same reset timestamp); only fetch-time-relative 5h/weekly reset times shift by the seconds between runs.
• Fresh agy cold start: keyring auth completes at ~+3.6s (ChainedAuth: authenticated via keyring in agy's own log), which is what the "first refresh can briefly fail" sentence refers to. The matching cold-start wait fix is in Fix Antigravity agy cold-start quota readiness wait #2665.

Test

• Docs only; no code changed.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 5, 2026, 9:57 PM ET / August 6, 2026, 01:57 UTC.

ClawSweeper review

What this changes

The PR documents Antigravity’s agy CLI and OAuth data sources when the desktop app is closed, and updates provider descriptions.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep open: the prior P2 documentation blocker remains. The new closed-app guidance omits the IDE fallback even though the current pipeline proceeds from app to agy CLI to IDE, then OAuth when eligible.

Priority: P3
Reviewed head: 6787aa4b1d1853cb7ac24dbc1528d760906fc31f

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The documentation is narrowly scoped and supported by runtime context, but it still misstates one implemented fallback stage.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only documentation, and its body supplies redacted live context for the claims.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only documentation, and its body supplies redacted live context for the claims.
Evidence reviewed	4 items	Current fallback implementation: Automatic mode resolves app, agy CLI, IDE, and then OAuth when credentials are available; the closed-app paragraph omits the IDE stage. Focused regression coverage: The provider test explicitly asserts app → CLI → IDE for CLI and automatic modes, and adds OAuth only for eligible automatic contexts. Unresolved prior finding: The changed paragraph still says the closed-app path uses only agy or OAuth, despite the listed IDE source immediately above it.
Findings	1 actionable finding	[P2] Include the IDE fallback in closed-app guidance
Security	None	None.

How this fits together

CodexBar’s Antigravity provider selects a local app server, agy CLI server, IDE server, or eligible Google OAuth source to obtain usage data. The selected result supplies quota and availability information to the menu bar and CLI.

flowchart LR
  App[Desktop app server] --> Select[Source selection]
  CLI[agy CLI server] --> Select
  IDE[IDE language server] --> Select
  OAuth[Eligible Google OAuth] --> Select
  Select --> Usage[Usage and quota snapshot]
  Usage --> Display[Menu bar and CLI output]

Loading

Before merge

• Add real behavior proof - Not applicable: This PR changes only documentation, and its body supplies redacted live context for the claims.
• Include the IDE fallback in closed-app guidance (P2) - The new sentence says a closed app uses only agy or OAuth, but Auto/CLI source selection tries the IDE language server after agy; users with an IDE available can otherwise be told the wrong fallback behavior. This remains the prior review blocker.
• Resolve merge risk (P1) - Merging leaves users with an active Antigravity IDE believing that lack of agy goes directly to OAuth, although the IDE source is attempted first.
• Complete next step (P2) - A one-paragraph documentation repair can resolve the concrete P2 finding without changing provider behavior.

Findings

• [P2] Include the IDE fallback in closed-app guidance — docs/antigravity.md:32-34

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	17 added, 2 removed across 3 documentation files	The narrow docs-only change makes exact fallback-order wording the material merge criterion.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Describe the closed-app automatic order as agy CLI, then IDE, then eligible OAuth, while retaining the caveat that OAuth availability rows are not full quota data.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Describe the closed-app automatic order as agy CLI, then IDE, then eligible OAuth, while retaining the caveat that OAuth availability rows are not full quota data.

Do we have a high-confidence way to reproduce the issue?

Yes: current source and focused tests establish that an available IDE is tried after agy and before eligible OAuth, contrary to the changed closed-app sentence.

Is this the best way to solve the issue?

No: the documentation must include the IDE stage so its described automatic fallback order matches the implementation.

Full review comments:

• [P2] Include the IDE fallback in closed-app guidance — docs/antigravity.md:32-34
  The new sentence says a closed app uses only agy or OAuth, but Auto/CLI source selection tries the IDE language server after agy; users with an IDE available can otherwise be told the wrong fallback behavior. This remains the prior review blocker.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4cdb349cbc57.

Labels

Label justifications:

• P3: This is a small documentation correction with limited user impact.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This PR changes only documentation, and its body supplies redacted live context for the claims.

Evidence

Acceptance criteria:

• [P1] git diff --check.
• [P1] make check.

What I checked:

• Current fallback implementation: Automatic mode resolves app, agy CLI, IDE, and then OAuth when credentials are available; the closed-app paragraph omits the IDE stage. (Sources/CodexBarCore/Providers/Antigravity/AntigravityProviderDescriptor.swift:175, 4cdb349cbc57)
• Focused regression coverage: The provider test explicitly asserts app → CLI → IDE for CLI and automatic modes, and adds OAuth only for eligible automatic contexts. (Tests/CodexBarTests/AntigravityCLIHTTPSFetchStrategyTests.swift:132, 4cdb349cbc57)
• Unresolved prior finding: The changed paragraph still says the closed-app path uses only agy or OAuth, despite the listed IDE source immediately above it. (docs/antigravity.md:32, 6787aa4b1d18)
• Feature history: The current descriptor has been recently maintained through Antigravity warm-session and provider-descriptor work; the CLI fallback dates to the dedicated introduction commit. (Sources/CodexBarCore/Providers/Antigravity/AntigravityProviderDescriptor.swift:175, 9c5628c08dc2)

Likely related people:

• Peter Steinberger: Recent descriptor refactors and the warm-agy isolation changes maintain the source-selection behavior this documentation describes. (role: recent area contributor; confidence: high; commits: fb66e63e8719, 9c5628c08dc2, 8af9a261b4a0; files: Sources/CodexBarCore/Providers/Antigravity/AntigravityProviderDescriptor.swift, Sources/CodexBar/Providers/Antigravity/AntigravityProviderImplementation.swift)
• Ellis Nieuwpoort: Introduced the agy CLI fallback whose documented behavior is being clarified. (role: introduced CLI fallback; confidence: high; commits: cd201b9e5035; files: Sources/CodexBarCore/Providers/Antigravity/AntigravityProviderDescriptor.swift)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Amend the closed-app paragraph to include the IDE fallback before OAuth.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (4 earlier review cycles)

• reviewed 2026-08-05T04:30:13.095Z sha 6787aa4 :: needs real behavior proof before merge. :: [P2] Preserve the IDE fallback in the closed-app guidance | [P2] Do not present unverified 100% model availability as quota
• reviewed 2026-08-05T05:05:43.099Z sha 6787aa4 :: needs real behavior proof before merge. :: [P2] Document the IDE fallback for closed-app mode
• reviewed 2026-08-05T06:44:32.274Z sha 6787aa4 :: needs real behavior proof before merge. :: [P2] Include the IDE fallback in closed-app guidance
• reviewed 2026-08-05T13:31:23.412Z sha 6787aa4 :: needs real behavior proof before merge. :: [P2] Include the IDE fallback in closed-app guidance

[steipete]

Landed. Verified before merge: every factual claim checked against source — ANTIGRAVITY_CLI_PATH is real, the cask installs agy, the 180s keep-alive matches AntigravityCLISession, and the providers.md endpoint correction (RetrieveUserQuotaSummary primary with GetUserStatus/GetCommandModelConfigs fallbacks) matches the probe's snapshot scoring — the old line was genuinely stale. Two maintainer touch-ups pushed before merge: kept the "(experimental)" tag in the README (the in-app toggle still carries it) and softened the cold-start sentence to reflect #2665's readiness wait, which landed in the same batch. Thanks @Yuxin-Qiao!