Antigravity Brain Explorer Skill (`agy-brain-explorer`)

An Antigravity Skill and companion CLI tool to discover, inspect, and audit Google Antigravity session trajectories, transcripts, tool invocations, and execution step outputs across all brain storage directories under ~/.gemini.

Packaged as an Antigravity agent skill under .agents/skills/agy-brain-explorer/ and powered by Typer, it equips both AI agents and developers to explore past conversations, trace execution flows, review tool parameters, and debug trajectories with Markdown-first rendering and clickable Antigravity conversation links (conversation://<session-id>).

Repository Structure

This repository is structured as a standalone Antigravity Skill package:

.
├── .agents/
│   └── skills/
│       └── agy-brain-explorer/
│           ├── SKILL.md                          # Skill definition & runbook for Antigravity agents
│           └── scripts/
│               └── agy-brain-explorer.py         # Standalone CLI exploration script (PEP 723)
├── brain.html                                    # Interactive Antigravity Brain Directory Specification
├── common.css                                    # Shared stylesheet for brain.html, index.html, and skill.html
├── index.html                                    # Interactive Code & Architecture Walkthrough (agy-brain-explorer.py)
├── skill.html                                    # Interactive Antigravity Skill Specification & SKILL.md Breakdown
├── LICENSE                                       # Apache 2.0 License
└── README.md                                     # Documentation and usage guide

SKILL.md: Teaches Antigravity agents how and when to invoke the tool, including required parameters, sandbox bypass instructions, and command recipes.
scripts/agy-brain-explorer.py: The executable Python script featuring PEP 723 inline metadata for zero-config execution via uv.
skill.html: Interactive Antigravity Skill Specification and annotated breakdown of SKILL.md, detailing agent progressive disclosure, sandbox bypass requirements, and interactive workflow execution.
brain.html: Interactive visual guide and technical specification covering the Antigravity Brain directory filesystem hierarchy, dual-mode JSONL transcripts, step execution logs, and metadata heuristics.
index.html: Syntax-highlighted, deep-dive code walkthrough of agy-brain-explorer.py across 18 architectural sections.
common.css: Shared CSS design system providing unified dark/light themes, typography, navigation, card components, and responsive layouts.

Using as an Antigravity Skill

1. Installation

You can install this skill either per-workspace or globally for all sessions on your machine:

Workspace Skill: Clone or copy this repository (or just the .agents/skills/agy-brain-explorer directory) into your workspace root.

Global Skill: Copy or symlink .agents/skills/agy-brain-explorer into your global Antigravity customizations folder:

mkdir -p ~/.gemini/config/skills
ln -s "$(pwd)/.agents/skills/agy-brain-explorer" ~/.gemini/config/skills/agy-brain-explorer

2. Progressive Disclosure & Agent Activation

Antigravity uses progressive disclosure. The agent sees the skill's name and description in its available skills list:

agy-brain-explorer: Discover, list, inspect, and audit Google Antigravity session trajectories, transcripts, tool invocations, and execution steps across all brain storage directories under ~/.gemini. Use whenever asked to list recent/past sessions, review session histories, inspect tool executions, or debug trajectory steps.

When prompted with queries such as:

"What did we do in our last session?"
"List my recent Antigravity conversations."
"Show me the commands run during session c1e9ba23."
"Audit the tool calls in step 5 of the previous task."

The agent activates the skill, reads SKILL.md, and runs the script using run_command.

3. Agent Sandbox Requirements

Important

When executed by an agent, run_command must specify BypassSandbox: true.

Antigravity session directories reside at ~/.gemini/**/brain/, outside standard workspace sandbox bounds.
uv run requires unsandboxed process creation permissions.

Standalone CLI Features

Multi-Brain Trace Explorer (Default): Running without arguments discovers all conversation traces across all brain directories under ~/.gemini (e.g. antigravity, antigravity-cli, antigravity-acp).
Prompt & Deep Transcript Search: Search sessions by initial user prompt or deeply across all conversation turns, model responses, and tool calls with --all-steps.
Side-by-Side Session Comparison (compare): Compare two sessions side-by-side to inspect differences in timing, duration, step counts, user turns, tool invocation frequencies, files modified, and outcomes.
On-Disk Path Inspection (paths): View exact on-disk directory paths, transcript.jsonl and transcript_full.jsonl files, sizes, step logs, scratch files, and workspaces with clickable markdown links.
Markdown-First Rendering: All results render cleanly as GitHub Flavored Markdown with clickable conversation:// session links that open directly in Antigravity and file:// links for local files.
Chronological Ordering: Traces are ordered by actual creation timestamp (newest first by default), rather than arbitrary directory sorting.
Interactive Trace Browser: Launch with --interactive / -i to view traces and select any session by numerical index to inspect its summary, timeline, or tools without typing long UUIDs.
Automated Session Discovery: Pass an absolute path, a local relative path, or just a session UUID prefix (e.g. 74126ecc). Sessions located anywhere under ~/.gemini/**/brain/ are automatically resolved.
Session Overview: Displays start/end timestamps in local time, elapsed duration, detected model, client timezone, mentioned items, workspace paths, and tool frequency metrics.
Interactive Timeline: Browse conversation turns with filters for tool calls (--tools-only), user inputs (--user-only), pagination, and offsets.
Detailed Step Inspection: Drill down into individual steps to view model thinking, prompt contents, formatted tool call arguments, and step output logs (output.txt).
Tool & Command Auditing: Dedicated commands to view all tool invocations or exclusively audit shell commands executed via run_command alongside their working directories.
Raw Step Record: Formatted JSON code block of any step for debugging.
Zero-Config Execution: Uses PEP 723 inline script metadata, allowing instant execution via uv without manually setting up a virtual environment.

Prerequisites

Python: >= 3.11
Dependencies: typer >= 0.12.0
Recommended Runner: uv

Quick Start

Using `uv` (Recommended)

Run directly with dependencies automatically resolved:

# Path to script from repository root
SCRIPT=".agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py"

# 1. Explore all conversation traces across ~/.gemini (newest first)
uv run $SCRIPT

# 2. Search sessions by prompt or deep transcript
uv run $SCRIPT search "create firmware"
uv run $SCRIPT search "build-docs" --all-steps

# 3. Compare two sessions side-by-side
uv run $SCRIPT compare 54cedc94 f779e57c

# 4. View on-disk locations and transcript paths
uv run $SCRIPT paths 54cedc94 f779e57c

# 5. Interactive trace browser (select by number to inspect)
uv run $SCRIPT -i

# 6. Filter traces or customize sorting
uv run $SCRIPT --limit 10
uv run $SCRIPT --asc              # Oldest first
uv run $SCRIPT --brain antigravity-cli

# 7. Inspect a specific session by UUID or prefix
uv run $SCRIPT 74126ecc-9639-4ff3-9dcb-7ac2d9400986
uv run $SCRIPT 74126ecc steps --limit 5
uv run $SCRIPT 74126ecc step 1

Tip

Add a shell alias for quick access anywhere:

alias agy-brain-explorer="uv run /path/to/.agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py"

Using standard `venv`

python3 -m venv .venv
source .venv/bin/activate
pip install "typer>=0.12.0"

# Run explorer
python .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py

# Inspect a session
python .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION_ID_OR_PATH> [COMMAND]

Command Reference

1. Conversation Trace Explorer (Default Mode)

When run without a session identifier (or with list / explore / traces), the explorer scans all brain directories under ~/.gemini and displays all discovered conversation traces ordered chronologically:

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py [OPTIONS]
# or explicitly:
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py list [OPTIONS]

Options:

-n, --limit <INT>: Limit number of traces displayed (default: 30).
-a, --all: Display all discovered traces without pagination limit.
--asc: Sort oldest first (default is newest first).
-b, --brain <STR>: Filter traces by brain root name (e.g. antigravity-cli).
-i, --interactive: Launch interactive session picker to inspect sessions by index number.
-m, --md, --markdown: Output as Markdown (default: True).
-h, --help: Show help and options.

Examples:

# View the 10 most recent traces in Markdown
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py --limit 10

# View only traces from antigravity-cli
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py --brain antigravity-cli

# Interactively browse and inspect sessions
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py -i

2. Search Sessions by Prompt or Deep Transcript (`search`)

Find sessions matching a keyword in the initial prompt or deep search across every step (prompts, model responses, tool arguments, and executed commands):

# Search sessions by initial user prompt across all brain directories
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py search "Please build a unified static HTML"

# Filter search to a specific brain root
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py search "build docs" --brain antigravity-cli

# Deep search across all conversation steps (user requests, model responses, tool args, commands)
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py search "build-docs-site.js" --all-steps

# Search within a single specific session
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> search "node --test"

Options:

-s, --all-steps: Deep search across all conversation turns, model responses, and tool calls.
-b, --brain <STR>: Filter search by brain root name.
-n, --limit <INT>: Limit number of matching results returned (default: 30).
-a, --all: Return all matching results without pagination limit.

3. Compare Two Sessions Side-by-Side (`compare`)

Compare two sessions side-by-side to review timing, duration, step counts, user turns, tool invocations, files created/modified, and final outcomes:

# Compare two sessions by IDs or prefixes
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py compare <SESSION_1> <SESSION_2>

# Or via session inspection syntax
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION_1> compare <SESSION_2>

4. Inspect On-Disk Locations and Transcripts (`paths`)

Display exact disk locations and clickable file links (file://) for session directories, transcripts (transcript.jsonl, transcript_full.jsonl), logs, step outputs, scratch files, and workspaces:

# Show disk paths for a single session
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> paths

# Show disk paths for multiple sessions simultaneously
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py paths <SESSION_1> <SESSION_2>

5. Single-Session Inspection

Inspect a specific session by supplying its full UUID, partial prefix, or folder path:

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py [OPTIONS] SESSION [COMMAND] [ARGS]...

`summary` (Default Session Subcommand)

Displays a high-level overview of the session, including metadata, timing, duration, workspace paths, initial user request, and tool invocation statistics in Markdown. Executed automatically when no subcommand is specified.

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION>
# or explicitly:
uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> summary

`paths` (Session File Locations)

Displays all on-disk locations (session directory, transcript.jsonl, transcript_full.jsonl, logs, step output files, scratch directory, and workspace) with clickable file:// links:

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> paths

`steps` (Timeline View)

Lists the conversation timeline in a Markdown table showing step number, time, actor source (USER_EXPLICIT, MODEL, SYSTEM), step type, and action/preview.

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> steps [OPTIONS]

-t, --tools-only: Filter to steps containing tool invocations.
-u, --user-only: Filter to user input steps.
-n, --limit <INT>: Limit number of steps displayed.
--offset <INT>: Skip initial number of steps.

`step` (Detailed Inspection)

Inspects a specific step in detail in Markdown. Displays metadata header, text content, model thinking (if present), formatted tool call arguments, and step output logs (output.txt).

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> step <STEP_INDEX> [OPTIONS]

-l, --lines <INT>: Maximum lines of step execution output to display (default: 50).

`tools` (Tool Call Audit)

Lists all tool calls executed across the entire session chronologically in Markdown, including tool name, action/summary, and arguments/target.

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> tools

`commands` (Shell Execution Audit)

Audits all shell commands executed via the run_command tool in a Markdown table. Displays step index, target working directory (Cwd), and the exact command line executed.

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> commands

`compare` (Session Comparison)

Compares this session against another session:

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> compare <OTHER_SESSION>

`raw` (Raw Step Dump)

Dumps the raw JSON record of a specific step index in a Markdown code block.

uv run .agents/skills/agy-brain-explorer/scripts/agy-brain-explorer.py <SESSION> raw <STEP_INDEX> [--full/--compact]

Session Resolution

The <SESSION> argument accepts:

Explicit Directory Path: Full or relative path to a session directory (e.g. ./74126ecc-9639-4ff3-9dcb-7ac2d9400986 or /path/to/session).
Session UUID: Full UUID corresponding to a folder in ~/.gemini/**/brain/<UUID>.
Prefix / Partial ID: The start of a UUID (e.g., 74126ecc). It searches all available Antigravity brain folders and resolves the match automatically.

Antigravity Session Directory Layout

For reference, session directories are structured as follows:

<session_dir>/
├── .system_generated/
│   ├── logs/
│   │   ├── transcript.jsonl        # Compact conversation history
│   │   └── transcript_full.jsonl   # Complete, untruncated transcript
│   └── steps/
│       └── <step_index>/
│           └── output.txt          # Raw output/log from step execution
├── scratch/                        # Temporary files generated during session
└── .user_uploaded/                 # Files uploaded by the user

License

Open source and available under the Apache License 2.0.

Disclaimer

This is not an official Google product.

Navigation Menu

Repository navigation

About

Repository files navigation

Antigravity Brain Explorer Skill (`agy-brain-explorer`)

Repository Structure

Using as an Antigravity Skill

1. Installation

2. Progressive Disclosure & Agent Activation

3. Agent Sandbox Requirements

Standalone CLI Features

Prerequisites

Quick Start

Using `uv` (Recommended)

Using standard `venv`

Command Reference

1. Conversation Trace Explorer (Default Mode)

2. Search Sessions by Prompt or Deep Transcript (`search`)

3. Compare Two Sessions Side-by-Side (`compare`)

4. Inspect On-Disk Locations and Transcripts (`paths`)

5. Single-Session Inspection

`summary` (Default Session Subcommand)

`paths` (Session File Locations)

`steps` (Timeline View)

`step` (Detailed Inspection)

`tools` (Tool Call Audit)

`commands` (Shell Execution Audit)

`compare` (Session Comparison)

`raw` (Raw Step Dump)

Session Resolution

Antigravity Session Directory Layout

License

Disclaimer

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/skills/agy-brain-explorer		.agents/skills/agy-brain-explorer
.gitignore		.gitignore
.nojekyll		.nojekyll
LICENSE		LICENSE
README.md		README.md
brain.html		brain.html
common.css		common.css
index.html		index.html
skill.html		skill.html

Latest commit

History

Folders and files

Repository files navigation

Antigravity Brain Explorer Skill (agy-brain-explorer)

Repository Structure

Using as an Antigravity Skill

1. Installation

2. Progressive Disclosure & Agent Activation

3. Agent Sandbox Requirements

Standalone CLI Features

Prerequisites

Quick Start

Using uv (Recommended)

Using standard venv

Command Reference

1. Conversation Trace Explorer (Default Mode)

2. Search Sessions by Prompt or Deep Transcript (search)

3. Compare Two Sessions Side-by-Side (compare)

4. Inspect On-Disk Locations and Transcripts (paths)

5. Single-Session Inspection

summary (Default Session Subcommand)

paths (Session File Locations)

steps (Timeline View)

step (Detailed Inspection)

tools (Tool Call Audit)

commands (Shell Execution Audit)

compare (Session Comparison)

raw (Raw Step Dump)

Session Resolution

Antigravity Session Directory Layout

License

Disclaimer

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Antigravity Brain Explorer Skill (`agy-brain-explorer`)

Using `uv` (Recommended)

Using standard `venv`

2. Search Sessions by Prompt or Deep Transcript (`search`)

3. Compare Two Sessions Side-by-Side (`compare`)

4. Inspect On-Disk Locations and Transcripts (`paths`)

`summary` (Default Session Subcommand)

`paths` (Session File Locations)

`steps` (Timeline View)

`step` (Detailed Inspection)

`tools` (Tool Call Audit)

`commands` (Shell Execution Audit)

`compare` (Session Comparison)

`raw` (Raw Step Dump)