feat: add antigravity-cli integration

[ludoo]

Register antigravity-cli as a Herdr integration target.

• Add install/uninstall hooks that write herdr-agent-state.sh and
  herdr-agent-state.ps1 to ~/.gemini/antigravity-cli/hooks/ and
  manage entries in hooks.json
• Support session resume via agy --conversation <id> when the
  integration reports a conversation ID
• Default config directory: ~/.gemini/antigravity-cli/ (overridable
  via ANTIGRAVITY_CLI_CONFIG_DIR)
• Update integrations docs, session-state docs, and API schema enum

refs #1011
refs #1571

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds Antigravity CLI as a supported Herdr integration. The change covers schemas, CLI registration, hook lifecycle management, agent-state reporting, session restoration, tests, and documentation.

Changes

Antigravity CLI support

Layer / File(s)	Summary
Integration contracts and registration src/api/schema/integrations.rs, src/integration/{env,mod,registry,types}.rs, docs/next/api/herdr-api.schema.json	Registers the target, configuration path, metadata, registry entry, result types, and API schema values.
Hook installation and removal src/cli/integration.rs, src/integration/{actions,targets,tests}.rs	Adds CLI aliases and lifecycle commands. It writes and removes managed hook configuration while preserving unrelated entries.
Agent-state hook assets src/integration/assets/antigravity_cli/*	Adds shell and PowerShell handlers for session, state, and release reporting.
Session restoration and documentation src/agent_resume.rs, docs/next/website/src/content/docs/{integrations,session-state}.mdx	Accepts Antigravity session IDs, plans agy --conversation <id>, validates references, and documents installation and restore behavior.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AntigravityCLI
  participant HerdrAgentStateHook
  participant HerdrServer
  AntigravityCLI->>HerdrAgentStateHook: Invoke lifecycle hook with JSON input
  HerdrAgentStateHook->>HerdrServer: Report conversation ID and agent state
  HerdrServer-->>HerdrAgentStateHook: Return pane update result
  HerdrServer->>AntigravityCLI: Resume with agy --conversation <id>

Loading

Possibly related issues

• [idea] Implement session restore for Antigravity (agy) #1824: Adds the requested Antigravity session tracking and restoration flow.

Possibly related PRs

• herdrdev/herdr#2036: Modifies related agent resume argument handling.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the antigravity-cli integration.
Description check	✅ Passed	The description is directly related to the changes and covers installation, configuration, session resume, and documentation updates.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[kangal-bot]

Hi @ludoo, thanks for your interest in contributing!

Herdr automatically admits focused bug fixes from contributors who are not maintainers when the title uses fix: ... or fix(scope): ... and the patch changes no more than 20 files and 1,000 total added or deleted lines.

Contributors who are not maintainers may submit only focused bug fixes. If this pull request fixes a bug, rename it to use a conventional fix: ... or fix(scope): ... title, then tag a maintainer to review and reopen it.

Feature requests, behavior changes, and other proposals belong in GitHub Discussions and require maintainer approval before a pull request.

If this gate classified the pull request incorrectly, reply and tag a maintainer listed in .github/MAINTAINERS. A verified maintainer can reopen it; reopening by anyone else will be closed again automatically.

Patch size: 15 changed files, 606 changed lines.

See https://github.com/herdrdev/herdr/blob/master/CONTRIBUTING.md for the contribution policy.

[ludoo]

@ogulcancelik This adds integration support for antigravity-cli, discussed in #1011 and #1571. Could you grant a scope override to reopen?

[greptile-apps]

Greptile Summary

Adds Antigravity CLI as an official session-restore integration.

• Installs platform-specific session hooks into the Antigravity configuration directory and manages a dedicated block in hooks.json.
• Reports conversation IDs and restores sessions with agy --conversation <id>.
• Registers the integration across detection, CLI, API schema, documentation, and tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported config-directory behavior is now an intentional, documented prerequisite with a regression test confirming that installation rejects rather than creates a missing directory.

Important Files Changed

Filename	Overview
src/integration/targets.rs	Implements Antigravity hook installation, configuration updates, and uninstall cleanup; the previously questioned missing-directory behavior is now documented and tested as an intentional prerequisite.
src/integration/env.rs	Resolves the Antigravity customization directory from ANTIGRAVITY_CLI_CONFIG_DIR or ~/.gemini/config.
src/integration/assets/antigravity_cli/herdr-agent-state.sh	Adds the Unix hook that reports Antigravity conversation identity without claiming lifecycle authority.
src/integration/assets/antigravity_cli/herdr-agent-state.ps1	Adds the equivalent Windows PowerShell conversation-reporting hook.
src/agent_resume.rs	Adds official Antigravity session-reference validation and resume planning through agy --conversation.
src/integration/tests.rs	Covers installation, replacement of stale owned configuration, missing-directory rejection, and uninstall behavior.

_{Reviews (10): Last reviewed commit: "fix: update antigravity session after co..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (2)

src/integration/mod.rs (1)

199-208: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use target-specific #[cfg] items for the hook assets.

These constants encode platform-specific behavior but use runtime-style cfg!(windows) selection. Define separate #[cfg(windows)] and #[cfg(not(windows))] constants instead.

Proposed refactor

-const ANTIGRAVITY_CLI_HOOK_INSTALL_NAME: &str = if cfg!(windows) {
+#[cfg(windows)]
+const ANTIGRAVITY_CLI_HOOK_INSTALL_NAME: &str = {
     "herdr-agent-state.ps1"
-} else {
+};
+#[cfg(not(windows))]
+const ANTIGRAVITY_CLI_HOOK_INSTALL_NAME: &str = {
     "herdr-agent-state.sh"
 };
-const ANTIGRAVITY_CLI_HOOK_ASSET: &str = if cfg!(windows) {
+
+#[cfg(windows)]
+const ANTIGRAVITY_CLI_HOOK_ASSET: &str =
     include_str!("assets/antigravity_cli/herdr-agent-state.ps1")
-} else {
+;
+#[cfg(not(windows))]
+const ANTIGRAVITY_CLI_HOOK_ASSET: &str =
     include_str!("assets/antigravity_cli/herdr-agent-state.sh")
-};
+;

As per coding guidelines, platform-specific Rust code must be compile-gated with target-specific #[cfg(...)].

Source: Coding guidelines

src/integration/assets/antigravity_cli/herdr-agent-state.ps1 (1)

59-90: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Rename $args to avoid shadowing PowerShell's automatic variable.

Static analysis flags reuse of the automatic $args variable at three call sites; $sessionArgs above already uses a distinct name for the same purpose.

🛠️ Proposed rename

     if ($Action -eq "release") {
-        $args = @(
+        $reportArgs = @(
             "pane",
             "release-agent",
             $env:HERDR_PANE_ID,
             "--source",
             "herdr:antigravity_cli",
             "--agent",
             "antigravity-cli",
             "--seq",
             "$seq"
         )
-        & herdr `@args` 2>$null | Out-Null
+        & herdr `@reportArgs` 2>$null | Out-Null
     } else {
-        $args = @(
+        $reportArgs = @(
             "pane",
             "report-agent",
             $env:HERDR_PANE_ID,
             "--source",
             "herdr:antigravity_cli",
             "--agent",
             "antigravity-cli",
             "--state",
             $Action,
             "--seq",
             "$seq"
         )
         if (-not [string]::IsNullOrWhiteSpace($conversationId)) {
-            $args += @("--agent-session-id", "$conversationId")
+            $reportArgs += @("--agent-session-id", "$conversationId")
         }
-        & herdr `@args` 2>$null | Out-Null
+        & herdr `@reportArgs` 2>$null | Out-Null
     }

Source: Linters/SAST tools

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6fc78bea-c8fa-4d98-bff4-a286dfb66023

📥 Commits

Reviewing files that changed from the base of the PR and between ac47b9e and 44d9211.

📒 Files selected for processing (15)

• docs/next/api/herdr-api.schema.json
• docs/next/website/src/content/docs/integrations.mdx
• docs/next/website/src/content/docs/session-state.mdx
• src/agent_resume.rs
• src/api/schema/integrations.rs
• src/cli/integration.rs
• src/integration/actions.rs
• src/integration/assets/antigravity_cli/herdr-agent-state.ps1
• src/integration/assets/antigravity_cli/herdr-agent-state.sh
• src/integration/env.rs
• src/integration/mod.rs
• src/integration/registry.rs
• src/integration/targets.rs
• src/integration/tests.rs
• src/integration/types.rs

[ludoo]

Pushed f71ca5e, which addresses every review comment and two further bugs found while verifying them.

Rather than take the review findings on trust, I drove a real agy 1.1.8 through Herdr panes and checked what the CLI actually does. That turned up more than the bots reported: the integration could never have worked as submitted, for three independent reasons.

Review comments

Finding	Outcome
hooks.json path (CodeRabbit, critical)	Fixed — ~/.gemini/config
flat vs grouped event shapes (CodeRabbit, major)	Fixed — grouped for tool events, flat for lifecycle
create the config dir (Greptile, P1)	Docs fixed instead; guard matches the other 13 integrations
cfg! → #[cfg] for hook assets	Fixed
$args shadowing in the PowerShell hook	Fixed — renamed to $reportArgs

On the last one, the suggested diff wrapped the splat in backticks (& herdr `@reportArgs` ). That is not valid splatting, so I applied the rename without it.

Bugs not raised in review

1. hooks.json is keyed by hook name, not by event. The old install wrote event arrays at the top level, which agy rejects outright:

failed to parse hooks.json: json: cannot unmarshal array into Go struct
field .PostInvocation of type jsonhook.JSONHookSpec

Confirmed against the file this PR had actually installed on my machine: loaded 0 named hooks. Herdr entries now live under a Herdr-owned "herdr" block that install rewrites and uninstall removes, leaving other named hooks alone.

2. The reported agent label could never match. The hooks reported antigravity-cli, but the server normalizes that to the canonical label agy before is_official_agent_source checks it — while that function matched on ("herdr:antigravity_cli", "antigravity-cli"). The pair was unreachable, so every session report was silently dropped and agy --conversation <id> resume was dead code. Both hook assets now report agy, like every other integration, and agent_resume.rs matches it.

Verification

End-to-end against a throwaway Herdr session running this build: agy now loads the hooks (1 named hooks, 5 total handlers, no parse errors), all five lifecycle events fire, and the conversation ID reaches Herdr:

{'agent': 'agy', 'kind': 'id', 'source': 'herdr:antigravity_cli',
 'value': '71b24d36-05b1-4911-9daa-006ddf8fd360'}

just check formatting passes and all 3118 tests pass. New coverage: both hook shapes per event, the named block, stale-block rewrite, missing-dir error, and foreign-hook preservation across install and uninstall.

[ogulcancelik]

thanks for adding this. i don’t think antigravity should report lifecycle state yet. full lifecycle authority requires complete coverage like kimi code and opencode, including working, idle, blocked, interruption/escape, and process/session termination transitions.

these hooks have no blocked transition, and interruption paths can miss postinvocation. stop is also mapped to release, although it represents the end of a turn rather than agent process exit. that can leave stale state or remove authority at the wrong time.

could we keep this integration session-only for now and continue using antigravity’s screen manifest for lifecycle state?

[ludoo]

thanks — agreed on all three points, changed in 2ae9acee.

worth adding one thing: antigravity only exposes PreToolUse, PostToolUse,
PreInvocation, PostInvocation and Stop. there is no SessionStart
equivalent. so blocked has no event to hang off at all, and coverage like kimi
code or opencode isn't just missing from this PR — it isn't reachable with the
current hook surface.

the integration is now session-only:

• registers one event, PreInvocation -> session
• sends only pane.report_agent_session (conversation id + transcript path)
• no pane.report_agent and no pane.release_agent anywhere in the script, so
  it cannot claim or drop lifecycle authority even by accident
• screen detection keeps owning state via src/detect/manifests/antigravity.toml

resume is unchanged: agy --conversation <id>.

verified live against antigravity cli 1.1.8:

idle     session=f553643b src=herdr:antigravity_cli
working  session=f553643b src=herdr:antigravity_cli
done     session=f553643b src=herdr:antigravity_cli
idle     session=f553643b src=herdr:antigravity_cli

herdr agent explain reports state coming from the stock remote agy.toml
(2026.06.24.1, local_override_shadowing_remote: false). the done -> idle
step is exactly where the old Stop -> release mapping used to drop authority
mid-session.

side effect worth noting: the hook previously ran on five event types including
every tool call. it now runs once per model invocation.

one caveat — the .ps1 is #[cfg(windows)]-gated and i could not validate it
locally, so CI is the only coverage on that path.

i left ANTIGRAVITY_CLI_HOOK_TIMEOUT_SEC at 10. hooks block the agent loop, and
10 is already a 3x tightening of antigravity's 30s default; the script's own
socket calls are capped at 0.5s each, so nothing in the healthy path gets near
it.