# Antigravity Power User Guide

A comprehensive reference for getting the most out of Antigravity.

---

## Glossary

| Term | Meaning |
|------|---------|
| **KI** | **Knowledge Item** — Persistent, curated knowledge distilled from conversations. Stored in `~/.gemini/antigravity/knowledge/` |
| **Artifact** | Files created during tasks: `task.md`, `implementation_plan.md`, `walkthrough.md`. Stored in `brain/<conversation-id>/` |
| **Brain** | The `~/.gemini/antigravity/brain/` directory — one subfolder per conversation containing artifacts |
| **Task Boundary** | The mechanism that creates the structured task UI during multi-step work |
| **Mode** | PLANNING → EXECUTION → VERIFICATION — the phases the agent moves through during a task |
| **Workflow** | Reusable procedure defined in `.agent/workflows/*.md` in your project |
| **Knowledge Subagent** | Separate async process that distills conversations into KIs after they occur |
| **Browser Recording** | WebP videos auto-saved when browser tools are used — stored in `browser_recordings/` |
| **MCP** | Model Context Protocol — for connecting external tools (configured in `mcp_config.json`) |

---

## Directory Structure

```
~/.gemini/antigravity/
├── brain/                      # Conversation artifacts
│   └── <conversation-id>/
│       ├── task.md             # Current task checklist
│       ├── task.md.resolved.N  # Version history
│       ├── implementation_plan.md
│       └── walkthrough.md
├── knowledge/                  # Knowledge Items
│   └── <ki-name>/
│       ├── metadata.json       # Title, summary, source refs
│       ├── timestamps.json     # Access/modification times
│       └── artifacts/          # The actual markdown docs
├── conversations/              # Encrypted conversation state (.pb)
├── implicit/                   # Encrypted implicit context (.pb)
├── browser_recordings/         # WebP videos from browser sessions
├── mcp_config.json            # MCP server configuration
└── user_settings.pb           # User preferences (encrypted)
```

---

## Power User Tips

### 1. Workflows with Turbo Mode

Create project-specific workflows in `.agent/workflows/` that the agent will follow:

```markdown
---
description: Deploy to production
---
// turbo-all
1. Run tests: `bin/agent_rake`
2. Build: `bundle exec rake build`
3. Push: `gem push pkg/*.gem`
```

**Annotations:**
- `// turbo` — Auto-run the next command without approval
- `// turbo-all` — Auto-run ALL commands in the workflow

**Usage:** Type `/deploy` or say "run the deploy workflow"

### 2. AGENTS.md — Your Control File

Create `AGENTS.md` in your project root with rules the agent will follow:

```markdown
## Commit Style
- Use Conventional Commits format
- Include AI attribution: `Co-authored-by: Antigravity <[email protected]>`

## Forbidden Actions
- Never modify files in `vendor/`
- Never push directly to `main`

## Definition of Done
- All tests pass (`bin/agent_rake`)
- CHANGELOG.md updated
- Documentation updated
```

### 3. Reference Past Conversations

The agent can search and retrieve context from previous conversations:

- "Look at the conversation where we refactored the API"
- "What did we decide about authentication last week?"
- "Check the implementation plan from conversation 922ca3e5..."

### 4. Artifact Version History

The `.resolved.N` files in `brain/` directories are version history:

```
task.md.resolved.0  # First version
task.md.resolved.1  # After first update
task.md.resolved.2  # After second update
task.md             # Current version
```

Useful for seeing how a plan evolved or recovering earlier versions.

### 5. Knowledge Items Are Editable

KI artifacts are just markdown files. You can:

- **Edit** them to correct mistakes
- **Delete** entire KI directories to remove outdated knowledge
- **Create** new ones manually (though the subagent usually handles this)

```bash
# View all KIs
ls ~/.gemini/antigravity/knowledge/

# Check KI metadata
cat ~/.gemini/antigravity/knowledge/*/metadata.json | jq .title
```

### 6. Image Generation

The agent can generate images for mockups, diagrams, and assets:

- "Generate a login page mockup"
- "Create an icon for the settings menu"
- "Design a dark mode version of this UI"

Generated images are saved as artifacts.

### 7. Browser Automation

The agent can control a real browser for:

- Testing web applications
- Filling forms and clicking buttons
- Debugging UI issues
- Taking screenshots

Recordings are automatically saved as WebP videos in `browser_recordings/`.

### 8. Experimental Conversations

If you're experimenting and don't want patterns codified as KIs, say:

> "This is experimental — don't create Knowledge Items from this."

Consider adding to `AGENTS.md`:

```markdown
## Experimental Conversations
If the user says "this is experimental", do NOT create Knowledge Items.
Mark any artifacts with a CAUTION banner.
```

---

## Useful Commands

```bash
# List all conversations with artifacts
ls ~/.gemini/antigravity/brain/

# Find recent KI updates
find ~/.gemini/antigravity/knowledge -name "*.md" -mtime -1

# View KI summaries
cat ~/.gemini/antigravity/knowledge/*/metadata.json | jq '{title, summary}'

# Check conversation artifact count
for d in ~/.gemini/antigravity/brain/*/; do echo "$(ls "$d" | wc -l) $d"; done | sort -rn | head -10

# Browser recording locations
ls ~/.gemini/antigravity/browser_recordings/*/metadata.json
```

---

## Encrypted Files (Read-Only)

The `.pb` files in `conversations/` and `implicit/` are encrypted Protocol Buffer files. They contain:

- Full conversation history
- Implicit context (workspace state, file contents, etc.)

**You cannot decode these** without Google's decryption keys. The human-readable exports are in `brain/` and `knowledge/`.

---

## MCP Configuration

To connect external tools, edit `~/.gemini/antigravity/mcp_config.json`:

```json
{
  "servers": {
    "my-tool": {
      "command": "/path/to/mcp-server",
      "args": ["--flag"]
    }
  }
}
```

The agent can then access resources and call tools from connected MCP servers.

---

*Last updated: 2026-01-03*

~/.gemini/antigravity/
├── brain/                      # Conversation artifacts
│   └── <conversation-id>/
│       ├── task.md             # Current task checklist
│       ├── task.md.resolved.N  # Version history
│       ├── implementation_plan.md
│       └── walkthrough.md
├── knowledge/                  # Knowledge Items
│   └── <ki-name>/
│       ├── metadata.json       # Title, summary, source refs
│       ├── timestamps.json     # Access/modification times
│       └── artifacts/          # The actual markdown docs
├── conversations/              # Encrypted conversation state (.pb)
├── implicit/                   # Encrypted implicit context (.pb)
├── browser_recordings/         # WebP videos from browser sessions
├── mcp_config.json            # MCP server configuration
└── user_settings.pb           # User preferences (encrypted)

---
description: Deploy to production
---
// turbo-all
1. Run tests: `bin/agent_rake`
2. Build: `bundle exec rake build`
3. Push: `gem push pkg/*.gem`

## Commit Style
- Use Conventional Commits format
- Include AI attribution: `Co-authored-by: Antigravity <[email protected]>`

## Forbidden Actions
- Never modify files in `vendor/`
- Never push directly to `main`

## Definition of Done
- All tests pass (`bin/agent_rake`)
- CHANGELOG.md updated
- Documentation updated

task.md.resolved.0  # First version
task.md.resolved.1  # After first update
task.md.resolved.2  # After second update
task.md             # Current version

# View all KIs
ls ~/.gemini/antigravity/knowledge/

# Check KI metadata
cat ~/.gemini/antigravity/knowledge/*/metadata.json | jq .title

## Experimental Conversations
If the user says "this is experimental", do NOT create Knowledge Items.
Mark any artifacts with a CAUTION banner.

# List all conversations with artifacts
ls ~/.gemini/antigravity/brain/

# Find recent KI updates
find ~/.gemini/antigravity/knowledge -name "*.md" -mtime -1

# View KI summaries
cat ~/.gemini/antigravity/knowledge/*/metadata.json | jq '{title, summary}'

# Check conversation artifact count
for d in ~/.gemini/antigravity/brain/*/; do echo "$(ls "$d" | wc -l) $d"; done | sort -rn | head -10

# Browser recording locations
ls ~/.gemini/antigravity/browser_recordings/*/metadata.json

{
  "servers": {
    "my-tool": {
      "command": "/path/to/mcp-server",
      "args": ["--flag"]
    }
  }
}