Antigravity Harness

A terminal-first CLI harness for the Google Antigravity IDE language-server agent.

Antigravity Harness wraps the local Antigravity language server and exposes a practical command-line workflow for agent sessions, system prompts, skills, MCP configuration, model discovery, and quota checks.

This repository does not vendor or redistribute Antigravity binaries. It discovers and invokes the Antigravity installation already present on your machine.

Features

• Interactive terminal chat backed by Antigravity -cli -agent_mode
• One-shot prompts through the language server -print mode
• Structured system-prompt injection
• Skills, agents, and workflow context loading from .agent
• MCP configuration management for ~/.gemini/antigravity/mcp_config.json
• /models and /quota commands for account/model state queries
• Native REPL passthrough mode
• LSP server launcher
• Permanent PATH installer
• Zero Python package dependencies

Requirements

• Linux
• Python 3.10+
• A local Antigravity install. The harness discovers it automatically from environment variables, PATH, and common install locations.
• An authenticated Antigravity IDE session for model/quota/agent requests

Installation

Clone the repository and install the agent:

git clone https://github.com/kaycke1337/antigravity-agent.git
cd antigravity-agent
./scripts/install.sh

For local development from an existing checkout, run the same installer from the repository root.

If your current shell does not pick up ~/.local/bin immediately:

source ~/.bashrc

Verify the installation:

agy-agent doctor

Quick Start

Start the interactive chat:

agy-agent

Run against a specific workspace:

agy-agent chat --workspace /path/to/project

Use a system prompt and skills:

agy-agent chat \
  --workspace /path/to/project \
  --system "You are a senior engineer. Be direct, pragmatic, and rigorous." \
  --skill frontend-design \
  --skill lint-and-validate

Run a one-shot prompt:

agy-agent ask "Review the modified files and summarize the risks" --workspace .

Read prompt text from stdin:

git diff | agy-agent ask --workspace . "Review this diff"

Interactive Commands

Inside agy-agent chat:

Command	Description
/help	Show available interactive commands
/status	Show active workspace, system prompt, skills, and MCP config
/skills	List discovered skills, agents, and workflows
/skill add <name>	Load a skill into the current session context
/skill clear	Clear active skills
/system	Print the active system prompt
/system <text>	Replace the session system prompt
/models	Ask the Antigravity language server for available models
/quota	Ask the language server for usage and quota state
/mcp	Show the active MCP configuration path
/doctor	Run local diagnostics
/attach	Hand the terminal directly to native agent_mode
/exit	Exit the harness

/models and /quota are routed through the language server so they can use the authenticated Antigravity account context. If the server cannot expose the data in the current environment, the agent is instructed to say what is missing instead of inventing values.

CLI Commands

agy-agent                     # default: opens chat
agy-agent chat                # interactive harness UI
agy-agent ask "prompt"        # one-shot prompt
agy-agent models              # one-shot model query
agy-agent quota               # one-shot quota query
agy-agent skills list         # list discovered skills
agy-agent skills show NAME    # print a skill file
agy-agent mcp path            # print active MCP config path
agy-agent mcp show            # print MCP config
agy-agent mcp install         # install kit MCP config into ~/.gemini/antigravity
agy-agent attach              # native agent_mode passthrough
agy-agent repl                # run agent_mode without local prompt UI
agy-agent lsp --port 8123     # start LSP mode
agy-agent raw -- -stamp       # pass raw flags to the language server
agy-agent doctor              # local diagnostics

Configuration

Antigravity discovery order:

1. ANTIGRAVITY_LS, when set to the language-server wrapper path
2. ANTIGRAVITY_HOME, ANTIGRAVITY_ROOT, or ANTIGRAVITY_DIR, when set to the install root
3. The antigravity executable on PATH
4. Common Linux install locations such as ~/Antigravity, ~/.local/share/Antigravity, /opt/Antigravity, and /usr/share/antigravity

Environment variables:

Variable	Default	Description
ANTIGRAVITY_LS	auto-detected	Direct path to the language-server wrapper
ANTIGRAVITY_HOME	auto-detected	Antigravity install root
ANTIGRAVITY_ROOT	auto-detected	Alternative Antigravity install root variable
ANTIGRAVITY_DIR	auto-detected	Alternative Antigravity install root variable
AGY_GEMINI_DIR	.gemini	Gemini directory passed to the language server
AGY_APP_DATA_DIR	antigravity	App data directory inside the Gemini directory
AGY_KIT_DIR	.agent	Skills/agents/workflows/MCP kit
AGY_MCP_CONFIG	auto-detected	Explicit MCP config path
AGY_INSTALL_DIR	$HOME/.local/bin	Install location used by scripts/install.sh

Common flags:

--workspace PATH
--system TEXT
--system-file PATH
--skill NAME
--skills-dir PATH
--mcp-config PATH
--continue
--conversation ID
--conversation-path PATH
--model-api-client-type ccpa|gemini
--dangerously-skip-permissions
--no-color

Skills

The harness discovers Markdown-based context packages from:

• $AGY_KIT_DIR/skills
• $AGY_KIT_DIR/agents
• $AGY_KIT_DIR/workflows
• <workspace>/.agent/skills
• <workspace>/.agents/skills

Examples:

agy-agent skills list
agy-agent skills show architecture
agy-agent chat --skill architecture --skill systematic-debugging

Selected skills are injected as structured context blocks before each user message.

MCP

Install the bundled kit MCP config:

agy-agent mcp install

Show the active MCP config:

agy-agent mcp show

By default, the target path is:

~/.gemini/antigravity/mcp_config.json

The sample config may contain placeholder values such as YOUR_API_KEY. Replace those before expecting the corresponding MCP server to work.

Architecture

The harness is intentionally small:

src/antigravity_harness/cli.py
scripts/install.sh

It starts the Antigravity language server with combinations of:

-cli
-agent_mode
-print
-enable_lsp
-lsp_port

System prompts, skills, and MCP references are injected as structured text because the language-server binary does not currently expose a documented system-prompt flag.

Troubleshooting

`agy-agent: command not found`

Run:

```bash
./scripts/install.sh
source ~/.bashrc

/models or /quota does not return data

Confirm that the Antigravity IDE is logged in and that the language server can access the authenticated account. The harness routes these requests through the server; it does not fabricate model or quota values locally.

License

MIT. This license applies to the harness code in this repository, not to the Antigravity IDE or its language-server binary.