Antigravity (Google) — Tool System¶
Built-in tools¶
Fixed set across all surfaces (2.0, CLI, SDK, IDE). Not individually toggleable; governed by the permissions engine. Names matter for hook matchers:
- Files/dirs:
view_file,write_to_file,replace_file_content,multi_replace_file_content,list_dir,find_by_name - Search/research:
grep_search,search_web,read_url_content - System/exec:
run_command,manage_task,schedule,list_permissions,ask_permission - Agent collaboration:
invoke_subagent,define_subagent,send_message,manage_subagents - Interaction/media:
ask_question,generate_image
Permissions engine¶
Every sensitive op is action(target), evaluated Deny > Ask > Allow (strict).
| Action | Target format | Default |
|---|---|---|
read_file |
read_file(/path), (dir), (*) |
Ask (workspace auto-allowed) |
write_file |
(/path), (*) — implicitly grants read |
Ask (workspace auto-allowed) |
read_url |
(domain), (*) |
Ask |
execute_url |
(domain), (*) — browser actuation |
Ask |
command |
(prefix), (regex), (*) |
Ask |
unsandboxed |
(prefix/regex/*) |
Ask |
mcp |
mcp(server/tool), mcp(server/*), mcp(*) |
Ask |
Implicit rules: write_file(X) grants read_file(X); deny read_file(X) blocks write_file(X); workspace files auto-allowed. Terminal sandbox (preview, macOS/Linux) compiles grants into FS/network allowlists. Interactive prompts allow scope editing for files/URLs/MCP but not commands.
Custom tools¶
No CLI function-tool format. Surface-dependent mechanisms:
1. Agent Skills¶
SKILL.md directory + YAML frontmatter (name optional, description required).
| Scope | Path |
|---|---|
| Workspace | <root>/.agents/skills/<name>/SKILL.md |
| Global (CLI/2.0) | ~/.gemini/config/skills/<name>/SKILL.md |
| Global (IDE) | ~/.gemini/antigravity/skills/<name>/SKILL.md |
| Backward-compat | .agent/skills/ (deprecated) |
2. Plugins¶
plugin.json manifest bundling skills/rules/MCP/hooks/sidecars.
<plugin>/
plugin.json # { "name": "..." } — name optional, defaults to dir
skills/ rules/ mcp_config.json hooks.json sidecars/
Discovery: .agents/plugins/<dir>/ or _agents/plugins/<dir>/ (workspace); ~/.gemini/config/plugins/<dir>/ (global).
3. Rules / context¶
.agents/rules/*.md (workspace — the IDE reads this, not a bare root AGENTS.md); ~/.gemini/GEMINI.md (global, user-managed).
4. Sidecars (background processes)¶
sidecar.json at ~/.gemini/config/sidecars/<name>/ or <plugin>/sidecars/<name>/. Fields: command (xor builtin, currently only schedule), args, restart_policy (always/on-failure/never), description, env, display_name. Disabled by default — enable in ~/.gemini/config/config.json: { "sidecar-name": { "enabled": true } }.
5. SDK custom subagents (Python)¶
Arbitrary Python callables registered as tools; declarative safety policies via deny()/allow()/ask_user() from google.antigravity.hooks.policy.
6. Hooks¶
hooks.json at .agents/hooks.json (workspace) or ~/.gemini/config/hooks.json (global).
{
"<hook-name>": {
"enabled": true,
"PreToolUse": [
{ "matcher": "run_command",
"hooks": [ { "type": "command", "command": "./script.sh", "timeout": 10 } ] }
],
"PostToolUse": [],
"PreInvocation": [],
"PostInvocation": [],
"Stop": [ { "type": "command", "command": "./gate.sh" } ]
}
}
| Event | Has matcher? | Purpose |
|---|---|---|
PreToolUse |
Yes | Before tool; can allow/deny/ask/force_ask |
PostToolUse |
Yes | After tool; returns {} |
PreInvocation |
No | Before model call; inject steps |
PostInvocation |
No | After tool calls; inject steps + control loop |
Stop |
No | On termination; "continue" re-enters loop |
Matchers: ""/"*" all, "run_command" exact, "a|b" either, "browser_.*" regex. Handler fields: type (only "command"), command, timeout (seconds in hooks.json, default 30). camelCase JSON via stdin/stdout.
Hook array shapes differ by event
PreToolUse/PostToolUse are arrays of { matcher, hooks[] }. Stop/PreInvocation/PostInvocation are flat arrays of handlers (no matcher wrapper). Mixing shapes silently fails to fire.
MCP tools — two files, two schemas¶
Antigravity writes MCP config to two files with different field names.
File 1 — mcp_config.json (Antigravity native / CLI)¶
Remote servers use serverUrl. url/httpUrl are explicitly not supported here.
{
"mcpServers": {
"sqlite-explorer": {
"command": "node",
"args": ["/usr/local/bin/sqlite-mcp-server.js"],
"env": { "SQLITE_DB_PATH": "/var/data/app.db" }
},
"my-remote-server": {
"serverUrl": "https://api.example.com/mcp/",
"headers": { "Authorization": "Bearer YOUR_API_TOKEN" }
}
}
}
Fields: command, serverUrl, args, env, cwd, headers, authProviderType ("google_credentials"), oauth ({clientId, clientSecret}), disabled, disabledTools.
File 2 — settings.json (open-source Gemini CLI)¶
Remote servers use httpUrl (or url+type). Per the official Gemini CLI JSON schema MCPServerConfig: command, args, env, cwd, url, httpUrl, headers, tcp (websocket), type (stdio/sse/http), timeout, trust.
Locations by surface¶
| Surface | Scope | Path | Format |
|---|---|---|---|
| 2.0 / IDE / CLI | Global | ~/.gemini/config/mcp_config.json |
serverUrl |
| IDE / CLI | Workspace | .agents/mcp_config.json |
serverUrl |
| Gemini CLI (OSS) | Global | ~/.gemini/settings.json |
httpUrl |
| Gemini CLI (OSS) | Workspace | .gemini/settings.json |
httpUrl |
| Plugin | any | <plugin>/mcp_config.json |
serverUrl |
Transports & auth¶
- stdio:
command+args+env. - Streamable HTTP / SSE:
serverUrl(mcp_config.json) /httpUrlorurl+type(settings.json). - WebSocket:
tcp(Gemini CLI schema only). - Auth: Google ADC (
authProviderType:"google_credentials"); OAuth auto-DCR; manualoauth:{clientId,clientSecret}(redirecthttps://antigravity.google/oauth-callback, tokens at~/.gemini/antigravity/mcp_oauth_tokens.json); customheaders.
Permissions & disabling¶
MCP governed by mcp action (default Ask). Disable specific tools: "disabledTools": ["dangerous_tool"]. Disable a server: "disabled": true. CLI /mcp overlay; MCP Store (40+ servers) in 2.0/IDE.
Gotchas¶
serverUrl(native) vshttpUrl(Gemini CLI) — wrong field is silently ignored. Write both files so both surfaces discover MCP.- Global skills/hooks live under
~/.gemini/config/, not~/.agents/. - IDE reads
.agents/rules/*.md, not a bare rootAGENTS.md(use a bridge file importing@/AGENTS.md). - Permissions are strict
Deny > Ask > Allow:command(*)in Ask +command(git)in Allow → git still prompts. - Scope editing on prompts unavailable for commands.
- Sidecars disabled by default; missing enable entry in
config.json= never runs. - Plugin-scoped skills live under
<plugin>/skills/; standalone under<scope>/skills/<name>/— not interchangeable. hooks.jsonStop/*Invocationare flat handler arrays;*ToolUseuse{matcher,hooks[]}.hooks.jsontimeoutis seconds; hooks embedded insettings.jsonmay be milliseconds per the schema — don't mix.- Antigravity is GUI-oriented; headless validation/init is a no-op.
- Antigravity has no commands surface (no
.agents/commands/discovery, no slash-command registration). The closest analog is orchestrator skills under.agents/skills/— load a skill as a subagent's instructions instead of a slash command.
Sources¶
- https://antigravity.google/docs/home
- https://antigravity.google/docs/permissions
- https://antigravity.google/docs/subagents
- https://antigravity.google/docs/mcp
- https://antigravity.google/docs/hooks
- https://antigravity.google/docs/plugins
- https://antigravity.google/docs/sidecars
- https://antigravity.google/docs/skills
- https://antigravity.google/docs/ide/skills
- https://antigravity.google/docs/settings
- https://antigravity.google/docs/sdk/overview
- https://antigravity.google/docs/cli/overview
- https://antigravity.google/docs/overview
- https://antigravity.google/docs/getting-started
- https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json
Non-doc corroboration
The two-file write strategy and pinned paths were additionally cross-checked against LazyAI's own packages/cli/internal/adapter/antigravity.go, mcp_compiler.go, and install tests (repo source, not official docs).