Antigravity Migration Is Really a .gemini to .agents Governance Migration

The Gemini CLI to Antigravity CLI migration is easy to describe badly: Google is moving developers from one command-line agent to another before a June 18 deadline. That framing is too shallow to be useful. The real migration is not from gemini to agy. It is from one governance model to another: directories change, MCP configuration moves, hook contracts are rewritten, skills shift locations, and static subagent definitions give way to dynamic orchestration.

That is why the new Google Cloud Community migration guide is worth attention. It does not merely say “install Antigravity.” It walks through file paths, config moves, hook rewrites, plugin imports, and a real Next.js/TypeScript mortgage analyzer project. With the June 18 Gemini CLI/Code Assist window close enough to make procrastination expensive, teams need mechanics more than positioning.

The article passed freshness checks with a June 3 timestamp and uses a concrete app rather than a contrived blank repository. The useful details are specific: Gemini user preferences and extensions live under ~/.gemini/; Antigravity consolidates settings in a user profile and can import Gemini extensions with agy plugin import gemini. Gemini MCP servers that previously lived inside settings.json under mcpServers move to standalone files: globally at ~/.gemini/config/mcp_config.json and locally at .agents/mcp_config.json. Repository config renames from .gemini/ to .agents/. Global shared skills move from ~/.gemini/skills/ to ~/.gemini/antigravity-cli/skills/.

That is not housekeeping. That is the safety surface.

The dangerous migration is the one that appears to work

The riskiest outcome is not that Antigravity fails to start. That would be obvious. The riskiest outcome is that it starts, edits files, calls tools, and appears healthy while your old safety assumptions quietly stopped applying.

If MCP servers move from an embedded settings object to standalone config files, you need to know which servers loaded from which scope. A global MCP server may not be appropriate for every repository. A local MCP server may be missing after the rename. If skills move directories, the agent may lose project-specific behavior or inherit global behavior you did not intend. If repository guidance moves from .gemini to .agents while GEMINI.md still parses, teams can end up with a hybrid workspace where some instructions are current and others are historical clutter wearing authority.

Practitioners should inventory before migrating. List existing .gemini/ contents, settings.json, mcpServers, hook scripts, skills, and static agents. Then migrate one repository first, not the whole portfolio. After the move, inspect the effective config. Do not trust a successful command invocation as proof that the workflow migrated.

This is the same trap teams hit during CI migrations. The build passing once does not prove secrets, branch protections, deployment gates, notifications, and rollback paths survived. Agent CLI migrations deserve the same suspicion because the agent can mutate code, invoke tools, browse, run shell commands, and in some setups touch external systems.

Hooks are contracts, not vibes

The guide’s most important technical detail is the hook rewrite. Gemini’s BeforeTool maps to Antigravity’s PreToolUse. Gemini’s run_shell_command maps to Antigravity’s run_command. More importantly, Antigravity hooks receive JSON on stdin and return JSON on stdout with a decision such as allow or deny.

That is a contract change. A hook that previously blocked by exit code is not automatically equivalent to one that must parse input and emit a decision object. If the port is sloppy, the failure mode may be fail-open. That is worse than no hook because the human thinks protection exists.

The migration guide’s destructive-command example blocks force pushes, hard resets, rm, chmod 777, and pipe-to-shell patterns like curl|bash or wget|sh. Those are good defaults, but the deeper lesson is testing. Every team should include a negative test in the migration: ask the agent to perform a known-forbidden action and verify the PreToolUse hook denies it with the expected JSON response. Capture the output. Put it in the migration notes. If you cannot prove the hook denies, you have not migrated the safety boundary.

There is also an implementation detail worth being blunt about: JSON parsing errors need explicit behavior. A hook that receives unexpected input should not accidentally allow the command because parsing failed. Defensive hooks should fail closed for destructive actions, log enough context for debugging, and avoid brittle substring checks where command normalization matters. Shell safety based on regex alone is never perfect, but a tested deny layer is still better than theatrical policy.

Dynamic subagents change review culture

Antigravity’s use of dynamic subagents and native artifacts such as Implementation Plan, Task, and Walkthrough reduces the need for static .gemini/agents/*.md role files. That is probably the right product direction. Static agent personas are easy to overfit, annoying to maintain, and often become prompt taxidermy: impressive labels, unclear behavior.

But static files had one virtue: they were inspectable. A reviewer could open the “security auditor” prompt or “test writer” prompt and see what it claimed to do. Dynamic subagents are more flexible, but they require the supervising agent to describe scope, outputs, and constraints clearly at runtime.

Teams should turn that into a process requirement. If the main agent spawns subagents, it should name each one, state its bounded task, list allowed write targets, and produce artifacts that can be reviewed. “I created some helpers” is not enough. Parallelism without boundaries is just faster confusion. The win from dynamic subagents is not that they feel autonomous; it is that they can decompose work while leaving reviewable evidence.

The migration plan should therefore be staged. First, port config and hooks. Second, import plugins and audit the result. Third, run a normal coding task with request-review permissions still enabled. Fourth, test denial hooks and MCP scope. Only after that should teams lean into dynamic subagents, planning artifacts, and browser-style validation.

The deadline creates urgency, but it does not excuse skipping the safety harness. If your team uses Gemini CLI only for toy prompts, the migration may be straightforward. If you use it for real repository work, MCP servers, custom skills, shell hooks, and role-specific agents, then Antigravity migration is a governance project. Treat it like one.

The blunt take: the command name is the least interesting part of this transition. The dangerous part is assuming your old controls survived because the new CLI can still edit code. Verify hooks. Verify MCP. Verify skills. Verify subagents. Then ship.

Sources: Migrating to Antigravity CLI — Google Cloud Community, Antigravity CLI documentation, Antigravity CLI overview