🚀 AGX — Antigravity Unified Management Suite

AGX (agx) is the ultimate CLI & IDE management suite for Google Antigravity. It enables bidirectional conversation index synchronization, zero-touch subdomain port forwarding, agentic browser window suppression, trajectory diffing, workspace migration, TOML config management, SQLite database vacuuming, state backups, and diagnostic health checks between Antigravity CLI and Antigravity IDE.

---

⚡ Key Features

• 🔄 Unified Index Synchronization: Keeps CLI SQLite indexes and IDE Protobuf global state (state.vscdb) in perfect harmony.
• 🌐 Subdomain Port Forwarding (agx tunnel): Zero-touch public subdomain forwarding (p<PORT>.avinya.it and <name>.avinya.it) via local Caddy reverse proxy router (:9999) behind Cloudflare Tunnel.
• 🥷 Agentic Browser Window Suppression (agx browser): Suppresses distracting agent browser popups via X11 stream watching (xdotool & xprop) and enforces GNOME strict window focus while CDP automation continues headlessly.
• ⚙️ Configuration TOML CRUD (agx config): Dot-notation CRUD engine (get, set, unset, show, path, init) for $XDG_CONFIG_HOME/agx/config.toml.
• 📊 Analytics Dashboard & JSON Exports (agx stats --json): Visualizes conversation distributions, step counts, and active workspaces with rich terminal charts or raw JSON arrays.
• 🧹 Database Defragmentation & Vacuum (agx prune --vacuum): Defragments SQLite database pages, cleans orphaned index records, and reclaims disk space with dynamic MB/KB space reporting.
• 🛡️ Central Version Shield (agx --force <cmd>): Centralized global version lock shield protecting commands against CLI/IDE version mismatches.
• 🔍 Full-Text Search (agx search <query> [--json]): Instant search across titles, UUIDs, and deep transcript logs.
• 🔀 Trajectory Diffing (agx diff <id1> <id2>): Compare conversation lengths, user prompt sequences, and turns side-by-side.
• 📂 Workspace Migration (agx rebind <old> <new>): Batch re-indexes conversations when repositories or folders move on disk.
• 💾 Full State Snapshots (agx backup, agx restore): Bundles brains, SQLite databases, and global state into compressed .tar.gz archives.
• 🩺 Diagnostic Health Check (agx doctor [--json]): Audits symlinks, SQLite query latencies (ms), X11 display server environment, XDG permissions, and available disk space.
• 🛡️ OS Compatibility Guards: Decorator-level platform verification (@require_platform([...])) enforcing runtime operating system checks.

---

📦 Installation & Setup

Quick Setup using uv (Recommended)

# Clone the repository
git clone https://github.com/hardik88t/agx.git
cd agx

# Install editable development mode
make editable

# Or reinstall globally into uv tool environment
make install

Shell Autocompletion Setup

# Install completion for Bash
agx --install-completion bash

# Or install completion for Zsh / Fish
agx --install-completion zsh

---

🛠️ Command Reference

Core Indexing & Synchronization

Command	Description
agx sync	Run bidirectional index synchronization
agx sync -r	Terminate IDE, sync database WAL caches, and relaunch IDE
agx list [-n 25] [-w <uri>] [--json]	List recent conversations in table or JSON format
agx search <query> [--json]	Full-text search across titles and transcript logs
agx stats [--json]	Workspace usage analytics and step count breakdowns
agx diff <id1> <id2>	Compare two conversation trajectories side-by-side

Management & Maintenance

Command	Description
agx browser stealth	Enable background agent browser window suppression daemon
agx browser normal	Disable suppression daemon and restore browser window visibility
agx browser toggle	Toggle browser suppression daemon state
agx browser status	Show suppression daemon PID and GNOME focus status
agx config get [key]	Read config setting (dot-notation e.g. section.key) or list all
agx config set <key> <val>	Update setting in config.toml (auto-casts numbers/booleans)
agx config unset <key>	Remove key from config.toml
agx config show / path	Display active config path and file contents
agx dedup [--apply]	Scan and delete duplicate conversation sessions
agx rebind <old> <new>	Rebind workspace path URIs when moving repositories
agx prune [--vacuum]	Prune orphaned records, dangling .tmp files, and defragment DBs
agx backup [-o <path>]	Create timestamped .tar.gz state snapshot archive
agx restore <path>	Restore conversation state from a backup archive
agx export <id> [-o <file.md>]	Export conversation transcript to clean Markdown document
agx doctor [--json]	Run diagnostic health audit (DB latency, X11, disk space, tunnel)
agx watch [--interval 5]	Background auto-sync watcher daemon

Subdomain Port Forwarding (agx tunnel)

Command	Description
agx tunnel <port> [name]	Forward local port to https://p<PORT>.<domain> or https://<name>.<domain>
agx tunnel start	Start Caddy reverse proxy router daemon (:9999)
agx tunnel stop / off	Stop Caddy router and deactivate all tunnel endpoints
agx tunnel status [--json]	Show router status, cloudflared daemon, domain, and active mappings
agx tunnel all / open	Scan active local listening dev servers and display auto-routed URLs
agx tunnel remove <name>	Remove a named subdomain mapping

---

💻 Makefile Shortcuts

The repository includes a helper Makefile for developer tasks:

make help             # Show available make targets
make editable         # Install agx in editable development mode (uv tool)
make install          # Reinstall agx globally in uv tool environment
make uninstall        # Uninstall agx from uv tool environment
make test             # Run pytest test suite
make lint             # Run Ruff linter
make format           # Run Ruff code formatter
make build            # Compile standalone single-file PyInstaller binary
make clean            # Clean build artifacts and pycache files

---

⚙️ Configuration (XDG Base Directory)

AGX follows the XDG Base Directory Specification:

• Config File: $XDG_CONFIG_HOME/agx/config.toml (default: ~/.config/agx/config.toml)
• State & Logs: $XDG_STATE_HOME/agx/ (default: ~/.local/state/agx/)
• Backups: $XDG_DATA_HOME/agx/backups/ (default: ~/.local/share/agx/backups/)

Initialize or view your configuration:

agx config init
agx config show

Environment Variable Overrides

Environment Variable	Default Value	Purpose
AGX_TARGET_CLI_VERSION	1.1.13	Target Antigravity CLI version lock
AGX_TARGET_IDE_VERSION	2.5.5	Target Antigravity IDE version lock
AGX_GEMINI_DIR	~/.gemini	Root Gemini Antigravity data folder
AGX_CLI_DIR	~/.gemini/antigravity-cli	Antigravity CLI directory
AGX_IDE_DIR	~/.gemini/antigravity-ide	Antigravity IDE directory
AGX_IDE_STATE_DB	OS-specific state.vscdb	Global VSCode/Electron state SQLite DB
AGX_TUNNEL_DOMAIN	avinya.it	Base domain for public subdomains
AGX_TUNNEL_ROUTER_PORT	9999	Local Caddy reverse proxy router port

---

📄 License

MIT License. Developed for the Antigravity developer community.