Adds first-class integration with Google's Antigravity IDE (https://antigravity.google/) as a third sibling to the existing Claude Code and Codex hook integrations. Strictly additive — no existing files in main are restructured. What ships ---------- * `.antigravity-plugin/` — verified-minimal plugin package: * `plugin.json` with `{"name": "mempalace"}` (no fabricated fields) * `mcp_config.json` registering the `mempalace-mcp` stdio server * `hooks.json.tmpl` templated with `__PLUGIN_DIR__` substitution * `skills/mempalace/SKILL.md` (real file — no symlinks) * `hooks/antigravity/`: * `lib/common.sh` — shared bash 3.2.57-compatible helpers with sentinel-guarded camelCase JSON parser, antigravity_*-namespaced state files, every existing kill switch, `MEMPAL_SAVE_INTERVAL >= 1` floor (no /0), and fail-open emitters * `mempal_save_hook_antigravity.sh` — Stop event handler: increments per-conversation counter, defers when fullyIdle=False or terminationReason=error, validates transcriptPath against `..` traversal, spawns `mempalace mine --mode convos` in a detached subprocess with a per-conversation pending marker, ALWAYS emits `{}` (never `{"decision":"continue"}` — that would force an infinite agent loop) * `mempal_wake_hook_antigravity.sh` — PreInvocation handler gated to invocationNum==1 with an atomic mkdir loop guard, runs `mempalace wake-up` with a 500ms hard timeout, emits verbatim output as `{"injectSteps":[{"ephemeralMessage":"..."}]}` or `{}` on any failure * `install.sh` — idempotent installer with cmp-gated copies, `__PLUGIN_DIR__` substitution, relative path absolutization, `--dry-run`, and basename-guarded `--uninstall` (refuses to wipe a directory whose basename isn't `mempalace`) * `INVESTIGATION.md` — verbatim quotes + URLs + dates from the five official Antigravity doc pages, recording every surface shipped and every surface deliberately omitted (PreCompact equivalent, slash-commands, rules/, plugin permissions field — the latter is third-party fabrication) * `STDIN_SHAPE.md` — exact stdin/stdout contract per event with worked examples * `README.md` — local hook docs + troubleshooting * `examples/antigravity/{hooks.json,mcp_config.json,README.md}` — standalone configs for users who don't want the full installer * `website/guide/antigravity.md` + sidebar entry — VitePress guide * Updates to `README.md`, `CHANGELOG.md` (Unreleased), `hooks/README.md` Tests (56 new, all passing) --------------------------- * `tests/test_antigravity_plugin_manifest.py` (11 tests) — schema contract on the in-repo `.antigravity-plugin/` directory, including guards against re-introducing the fabricated `permissions` field and against any symlink leak. * `tests/test_antigravity_hooks_shell.py` (31 tests) — invokes the bash hooks via subprocess with synthetic camelCase stdin, asserts `{}` on every failure path, kill-switch coverage (env vars + config.json + palace nuke), divide-by-zero floor, transcript traversal rejection, namespacing, wing inference, and the hard refusal to ever emit `decision=continue` from the Stop hook. * `tests/test_antigravity_hooks_install.py` (14 tests) — `--dry-run` side-effect-free, real install layout, executable bits preserved, byte-identical idempotent re-runs (md5 + filecmp), basename-match uninstall safety, refusal when plugin.json is missing or names a different plugin, relative path absolutization. Skipped on Windows. Verification ------------ * `uv run pytest tests/ --ignore=tests/benchmarks -v` → 2314 passed, 3 skipped (Windows), 1 unrelated warning * `uv run ruff check .` → all checks passed * `uv run ruff format --check .` → 139 files already formatted * `bash -n` clean on common.sh, both hook scripts, install.sh * Local install at `~/.gemini/config/plugins/mempalace/` verified end- to-end: layout correct, paths absolutized in hooks.json, both hooks fire with realistic camelCase JSON in <1s, wing inference picks `wing_mempalace` from workspacePaths[0], state files all `antigravity_*`-namespaced, second `install.sh` run produces byte-identical output (md5 snapshots match), uninstall removes only the mempalace plugin and leaves all 6 sibling Google plugins untouched. Constraints honoured -------------------- bash 3.2.57 (no mapfile / readarray / declare -A / `${var^^}`), verbatim guarantee on all wake injections, hooks <500ms / startup injection <100ms target (kill-switch path returns in <1.5s in CI), zero new runtime dependencies, no telemetry, no external API, strictly additive (existing Claude/Codex hooks unchanged). Refs: hooks/antigravity/INVESTIGATION.md for the full audit.
15 KiB
Antigravity IDE — Integration Surface Investigation
Investigated: 2026-05-27 Author: undeadindustries Scope: What MemPalace can integrate with in Google's Antigravity IDE, what we shipped, and what we deliberately did not ship.
This document is the source of truth for design decisions in the
feat/antigravity-support branch. It exists so a future maintainer can
re-derive every choice without re-reading the docs cold.
1. Surfaces verified against Google's official Antigravity docs
All quotes are pulled verbatim from Google's official Antigravity documentation on 2026-05-27. URLs are the authoritative source; the mirrored excerpts here are for reviewer convenience.
1.1. MCP — https://antigravity.google/docs/mcp
The configuration file is located at
~/.gemini/antigravity/mcp_config.json.The configuration file has a single
mcpServersobject where you define each server you want to connect to.
Schema (verified):
{
"mcpServers": {
"<name>": {
"command": "...", // stdio
"args": [...],
"env": {...},
"cwd": "...",
"serverUrl": "...", // remote
"headers": {...},
"authProviderType": "google_credentials",
"oauth": {"clientId": "...", "clientSecret": "..."},
"disabled": false,
"disabledTools": [...]
}
}
}
Per-plugin form: mcp_config.json at the plugin root, same shape.
Antigravity merges plugin entries with the user's
~/.gemini/antigravity/mcp_config.json rather than clobbering.
Cross-checked locally: the user's existing
~/.gemini/antigravity/mcp_config.json already contains a working
"mempalace": {"command": "/Users/robs/.local/bin/mempalace-mcp"}
entry, proving the shape matches and the binary is on PATH.
1.2. Plugins — https://antigravity.google/docs/plugins
A plugin is a directory containing a
plugin.jsonfile and optional subdirectories for different customization types:plugins/<plugin-name>/ ├── plugin.json # Required marker file ├── mcp_config.json # Optional MCP server definitions ├── hooks.json # Optional hooks definition ├── skills/ # Optional skills │ └── <skill-name>/ │ └── SKILL.md └── rules/ # Optional rules └── <rule-name>.md
Manifest schema (verified):
{
"name": "my-custom-plugin"
}
The name field is optional and defaults to the directory name if omitted.
Install locations (verified):
- Workspace Level: Place your plugin folder inside a
.agents/plugins/or_agents/plugins/directory at the root of your opened workspace.- Global Level: Place your plugin folder inside
~/.gemini/config/plugins/in your user home directory.
We ship the global location as the canonical install path.
1.3. Skills — https://antigravity.google/docs/skills
A skill is a folder containing a
SKILL.mdfile with instructions that the agent can follow when working on specific tasks.
Frontmatter (verified):
| Field | Required | Description |
|---|---|---|
name |
No | A unique identifier (lowercase, hyphens). Defaults to the folder name. |
description |
Yes | A clear description of what the skill does and when to use it. |
Standalone discovery paths (verified):
| Location | Scope |
|---|---|
<workspace>/.agents/skills/ |
Workspace-specific |
~/.gemini/antigravity/skills/ |
Global, all workspaces |
In-plugin discovery: <plugin>/skills/<skill-name>/SKILL.md.
We ship the in-plugin form so a single install registers MCP, skill, and hooks together.
1.4. Hooks — https://antigravity.google/docs/hooks?app=antigravity
Hooks allow you to run custom scripts or shell commands at specific points during Antigravity's execution loop.
hooks.json lives at one of:
~/.gemini/config/hooks.json(global)<workspace>/.agents/hooks.json(workspace)<plugin-root>/hooks.json(per-plugin) — what we ship
Top-level schema (verified):
{
"<hook-name>": {
"enabled": true,
"PreToolUse": [{ "matcher": "...", "hooks": [{...}] }],
"PostToolUse": [{ "matcher": "...", "hooks": [{...}] }],
"PreInvocation": [{ ... }],
"PostInvocation": [{ ... }],
"Stop": [{ ... }]
}
}
For PreInvocation / PostInvocation / Stop, items are flat handler
objects; the matcher wrapper is only used for PreToolUse /
PostToolUse.
Handler object (verified):
| Field | Required | Description |
|---|---|---|
type |
No | Currently only "command" is supported. Default. |
command |
Yes | The shell command to execute. |
timeout |
No | Timeout in seconds. Defaults to 30. |
STDIN/STDOUT contract (verified)
Hooks receive input via stdin as JSON and should return output via stdout as JSON. Field names use camelCase.
Common stdin fields (every event):
| Field | Type | Description |
|---|---|---|
conversationId |
string | The unique UUID of the active agent conversation. |
workspacePaths |
array | Absolute directory paths of the user's workspaces. |
transcriptPath |
string | Absolute path to the persistent transcript.jsonl. |
artifactDirectoryPath |
string | Path to conversation artifacts and screenshots. |
Stop event additional fields:
| Field | Type | Description |
|---|---|---|
executionNum |
integer | Sequence number of the execution attempt. |
terminationReason |
string | "model_stop", "max_steps_exceeded", "error", etc. |
error |
string | Optional error message. |
fullyIdle |
boolean | Required. True iff all background commands and async tasks are done. |
Stop event stdout (verified):
| Field | Type | Description |
|---|---|---|
decision |
string | Required. Set to "continue" to FORCE the agent to keep running. Anything else allows the stop. |
reason |
string | Optional. If decision == "continue", injected as a system message. |
CRITICAL: emitting {"decision": "continue"} from a save hook would
turn it into an infinite agent-loop trigger. The MemPalace save hook
MUST emit {} on every code path. There is an explicit refusal in
mempal_save_hook_antigravity.sh to ever print the literal word
"continue" from a decision field.
PreInvocation event additional fields:
| Field | Type | Description |
|---|---|---|
invocationNum |
integer | Sequence number of the current model invocation. |
initialNumSteps |
integer | Number of steps currently in the trajectory. |
PreInvocation event stdout (verified):
| Field | Type | Description |
|---|---|---|
injectSteps |
array | Optional. Steps injected before the model is called. Each step has one of: |
{ "toolCall": {...} } / { "userMessage": "..." } / { "ephemeralMessage": "..." } |
We use ephemeralMessage for the wake-up injection: the message is
visible to the model on this turn but does not persist to the
transcript, so we do not pollute future model calls with the same
injection.
PreInvocation fires before EVERY model invocation, not only at session
start. We gate to invocationNum == 1 to mimic Cursor's sessionStart
semantics — exactly one wake injection per conversation.
1.5. Permissions — https://antigravity.google/docs/permissions
Permissions are user-side, configured via Allow / Deny / Ask lists.
Plugins do not declare permissions in plugin.json. The
third-party "antigravity-plugins" community skill at
~/.gemini/skills/antigravity-plugins/SKILL.md documents a
"permissions": [...] field in plugin.json; that field is fabricated
and does not appear in any real Google-shipped plugin (firebase,
google-antigravity-sdk, chrome-devtools-plugin,
modern-web-guidance-plugin) inspected at
~/.gemini/config/plugins/.
We ship a minimal plugin.json of {"name": "mempalace"}.
2. Surfaces shipped
| Surface | What we ship |
|---|---|
| Plugin manifest | .antigravity-plugin/plugin.json — minimal, verified shape |
| MCP auto-registration | .antigravity-plugin/mcp_config.json — registers mempalace-mcp stdio |
| Skill | .antigravity-plugin/skills/mempalace/SKILL.md — real file, frontmatter |
Stop hook |
hooks/antigravity/mempal_save_hook_antigravity.sh — counter + auto-mine |
PreInvocation hook |
hooks/antigravity/mempal_wake_hook_antigravity.sh — wake injection |
| Installer | hooks/antigravity/install.sh — idempotent, basename-match uninstall |
| User-facing docs | website/guide/antigravity.md + sidebar wiring |
| Examples | examples/antigravity/{hooks.json,mcp_config.json,README.md} |
| Tests | 3 test files mirroring the cursor blueprint |
3. Surfaces deliberately not shipped
3.1. PreCompact equivalent — NOT SHIPPED
Antigravity's external hooks.json does not expose a context-compaction event. The Python SDK has an in-process @hooks.on_compaction
decorator (see ~/.gemini/config/plugins/google-antigravity-sdk/examples/getting_started/hooks.md),
but that fires inside a Python LocalAgentConfig-built agent, not the
IDE itself. There is no way to subscribe to compaction from a
plugin's hooks.json.
UX consequence: long conversations can auto-compact without a save
checkpoint. The Stop hook still catches the conversation when the
user actually ends the turn, so the worst case is that some mid-turn
state is lost on auto-compaction. Verbatim transcript ingestion via
the Stop path covers the long-term recall use case.
3.2. Slash-commands / commands/ — NOT SHIPPED
Antigravity has no commands/ plugin component. The Cursor and Codex
integrations both ship five quick-reference commands
(mempalace-help, -init, -mine, -search, -status) that point
at mempalace instructions <cmd>. Those have been folded into the
SKILL.md ## Common operations section so the agent gets the same
quick-reference content via Antigravity's progressive-disclosure skill
loading. No new files, no rule-noise, same discoverability.
3.3. rules/ — NOT SHIPPED
rules/<name>.md files are evaluated as constraints on the agent's
behavior. Shipping rules from MemPalace risks colliding with the
user's existing project rules (e.g. .agents/rules/*.md files the
user has already authored). Users who want strict MemPalace-related
rules can drop them into their own <workspace>/.agents/rules/
directory; we do not impose them.
3.4. Workspace-level .agents/plugins/mempalace/ install — NOT SHIPPED BY DEFAULT
The installer writes to the global location at
~/.gemini/config/plugins/mempalace/. Workspace-scoped installs are
documented in hooks/antigravity/README.md for users who want to
limit MemPalace to one workspace; they can cp -r .antigravity-plugin <workspace>/.agents/plugins/mempalace. We do not install there
automatically because the canonical UX is global.
3.5. permissions field in plugin.json — NOT SHIPPED
Antigravity permissions are user-side (Allow / Deny / Ask
lists). Plugin manifests do not declare permissions. The
"permissions": [...] field documented in the third-party
"antigravity-plugins" community skill is fabricated; no
Google-shipped plugin uses it.
3.6. PreToolUse / PostToolUse hooks — NOT SHIPPED
These would let MemPalace observe every tool call (e.g.
auto-extract entities after each write_to_file). Out of scope
for v1; the hook surface is real and could be added in a future
PR if there is demand. Documenting the omission here so a future
contributor doesn't conclude the hooks weren't supported.
4. Cross-checks against the user's running Antigravity
The user (robs@) has Antigravity 2.0 installed. The following live
artifacts on this machine corroborate the published docs:
| Path | Confirms |
|---|---|
~/.gemini/antigravity/mcp_config.json |
MCP config path + standard mcpServers shape |
~/.gemini/antigravity/skills/<skill-name>/SKILL.md (multiple) |
Global skill discovery path |
~/.gemini/config/plugins/firebase/plugin.json |
Real plugin.json shape (no permissions field) |
~/.gemini/config/plugins/chrome-devtools-plugin/skills/.../SKILL.md |
In-plugin skill discovery <plugin>/skills/<name>/SKILL.md |
~/.gemini/config/plugins/google-antigravity-sdk/examples/.../hooks.md |
SDK-side compaction hook is in-process Python only |
Existing mempalace entry in mcp_config.json |
mempalace-mcp already running and discoverable |
5. Reference URLs (all 2026-05-27)
https://antigravity.google/docs/pluginshttps://antigravity.google/docs/hooks?app=antigravityhttps://antigravity.google/docs/skillshttps://antigravity.google/docs/mcphttps://antigravity.google/docs/permissionshttps://antigravity.google/docs/subagentshttps://antigravity.google/blog/introducing-google-antigravity-sdk