paragravity README

The project's README from github.com/edison-land/paragravity. As one markdown file: README.md.

🌌 ParaGravity (pgrav)

Native, non-invasive parallel multi-account & sandbox manager for Google Antigravity.
Run multiple Google Gemini Pro accounts side-by-side in independent, isolated windows on macOS and Windows.

English | 简体中文

License: MIT Platform: macOS | Windows Python: 3.8+ PRs Welcome

✨ Key Advantages

🚀 Quick Start

curl -fsSL https://raw.githubusercontent.com/edison-land/paragravity/main/install.sh | bash

2. Windows Quick Start (PowerShell / CMD)

Clone the repository and add the bin directory to your user PATH:

git clone https://github.com/edison-land/paragravity.git $HOME\.paragravity
# Add $HOME\.paragravity\bin to PATH, then use:
pgrav create work

💡 Windows notes

  • Open a new terminal after updating PATH — already-open shells won't pick up the change.
  • python must be on PATH (any Python 3.8+ install works).
  • Git Bash (MSYS2) is fully supported. bin/pgrav is a real POSIX script rather than a symlink, so it survives clones made with Windows' default core.symlinks=false and forwards arguments correctly. In CMD/PowerShell the bundled pgrav.cmd is used automatically.

3. Homebrew Tap (Coming Soon)

brew tap edison-land/tap
brew install paragravity

📖 CLI Usage

💡 Tip: Both pgrav (short) and paragravity (full) are registered and ready to use!

1. Create an Isolated Profile

Create a new sandbox with a single command:

pgrav create zwe

This instantly:

To launch immediately upon creation:

pgrav create work --launch

To keep real ~/.ssh / ~/.config out of reach of agents running inside the profile, tighten the symlink policy with --links (default full preserves the original behavior):

pgrav create work --links minimal   # link git/shell configs and project dirs, skip .ssh/.config
pgrav create work --links none      # link almost nothing (keychain bridge only)

Inherit or Clone Configuration (No More Blank Canvas!)

New profiles start clean, but you often want your custom keybindings, editor settings, snippets, agent skills, or MCP tools without having to re-configure them.

🔒 Security Guarantee: Strict credential and session isolation. OAuth tokens (jetski-standalone-oauth-token, oauth_creds.json), Google account IDs, cookies, local storage, and conversation histories are NEVER copied or inherited. All profiles are created with owner-only (0700/0600) permissions.

2. List All Profiles & Status

View all your parallel instances, live process status, and bound Google accounts:

pgrav list
# or simply:
pgrav ls

💡 Computing on-disk size walks every file in the profile, which is slow once profiles grow — so it is off by default. Use pgrav list --size when you need it, or pgrav list --json for machine-readable output in scripts/CI.

Example Output:

PROFILE            STATUS         PID      ACCOUNT (GOOGLE)               SIZE       DESCRIPTION
───────────────────────────────────────────────────────────────────────────────────────────────
zwe                ● Running      49377    [email protected]              —          Development account
work               ○ Stopped      -        [email protected]               —          Company projects

3. Launch an Instance

pgrav launch zwe

Or simply press Cmd + Space anywhere on your Mac and type Antigravity (zwe)!

You can also open a project folder directly at launch:

pgrav launch zwe ~/Projects/demo

4. Stop a Running Instance

pgrav stop zwe

Stopping is staged: the Electron main process first gets a chance to shut down cleanly and save workspace state, straggler children are reaped next, and only --force escalates to SIGKILL.

5. View Instance Logs

Background launches now write stdout/stderr to ~/.antigravity-profiles/<name>/logs/, so startup failures, sign-in and token-refresh issues are no longer invisible:

pgrav logs zwe         # tail of the latest launch log
pgrav logs zwe -f      # follow live output
pgrav logs zwe -n 200  # last 200 lines

6. Inspect Profile Details

pgrav info zwe
# scripts/CI: pgrav info zwe --json

7. Delete a Profile

pgrav delete zwe

8. Modern Web Console & Floating Widget

Manage all your instances visually with zero dependencies:

# Launch full Web Console (Matrix grid, batch controls, macOS window tiling)
pgrav web
# or simply:
pgrav ui

# Launch compact floating widget HUD
pgrav widget
# or:
pgrav ui --widget

Tip: Visit http://127.0.0.1:3888 for the full console or http://127.0.0.1:3888/widget for the compact HUD view.

🗑️ Uninstall

# Remove the CLI (skip the brew line if you didn't use Homebrew)
brew uninstall paragravity   # or: rm ~/.local/bin/paragravity ~/.local/bin/pgrav

# Remove every profile sandbox (⚠️ permanently deletes all sign-in state and data)
rm -rf ~/.antigravity-profiles

# Remove the generated profile launchers
rm -rf ~/Applications/Antigravity\ \(*\).app

# Finally, remove the `export PATH="$HOME/.local/bin:$PATH"` line install.sh
# appended to your shell rc file, if present.

🔐 Security Notes

🏗️ Technical Architecture

ParaGravity achieves completely clean, isolated execution through three native mechanisms:

┌──────────────────────────────────────────────────────────────┐
│                    macOS Host Environment                    │
│                                                              │
│  [Official App]          [Profile A: zwe]    [Profile B: work]
│  /Applications/          ~/.antigravity-     ~/.antigravity- 
│  Antigravity.app         profiles/zwe        profiles/work   
│  (washingshop account)   (zwe account)       (work account)  
│                                                              │
│  ├── default Library/    ├── data/           ├── data/       
│  └── default Keychain    └── home/           └── home/       
│                              ├── .gemini/        ├── .gemini/
│                              └── isolated        └── isolated
│                                  tokens              tokens  
└──────────────────────────────────────────────────────────────┘
  1. Storage Sandboxing (--user-data-dir): Each profile maintains its own Chromium partition, SQLite databases, IndexedDB, extensions, and workspace state.
  2. Environment & Keychain Isolation (SSH_CONNECTION=1): Electron/Language Server automatically falls back to file-based token storage within the profile's isolated directory, preventing keychain contention with the host instance.
  3. Native macOS Application Bundles: Every profile has a dedicated .app bundle registered in ~/Applications, making Antigravity multi-instance a first-class citizen in macOS.

🤝 Contributing

Contributions are warmly welcomed! Please feel free to submit an Issue or Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

👥 Contributors

Huge thanks to the contributors who helped shape ParaGravity:

📄 License

Distributed under the MIT License. See LICENSE for more information.

⚠️ Disclaimer

ParaGravity is an open-source utility that leverages standard Chromium command-line options. It is not affiliated with, sponsored by, or endorsed by Google LLC. All trademarks belong to their respective owners.

paragravity (edison-land/paragravity)

Searching Database…

233 ·GitHub
Paragravity
What is this?ParaGravity (pgrav) is a native, non-invasive manager that runs multiple Google Antigravity (Gemini Pro) accounts side-by-side in separate, isolated windows on macOS and Windows.
How does it keep the accounts isolated — does it patch Antigravity?It never patches Antigravity: each profile is simply a Chromium --user-data-dir partition with its own extensions, IndexedDB, local storage and chat history, wrapped in a native macOS .app bundle or Windows shortcut.
How do I get my first sandbox running?On macOS there is a one-line install; on Windows clone the repo and add its bin directory to PATH. One pgrav command then creates a sandbox under ~/.antigravity-profiles plus a native .app or Start Menu shortcut you launch via Spotlight or Windows Search.
What do I need to have installed before using it?Google Antigravity itself and Python 3.8+ on PATH; pgrav itself has zero external pip or npm dependencies. Git Bash (MSYS2) is fully supported on Windows.
Does it work on Linux, or is it macOS and Windows only?macOS and Windows only — Linux is not mentioned anywhere; profiles materialize as .app bundles on macOS and Desktop/Start Menu .lnk shortcuts on Windows.
Is it safe to let coding agents run inside a profile — where do my Google credentials end up?OAuth tokens are stored as plaintext files inside each profile, so never sync or back up ~/.antigravity-profiles to cloud drives or repos. Profiles also symlink real folders like ~/.ssh and ~/.config by default — tighten with --links minimal or none before letting agents in.
Is it free and open source?Yes — MIT-licensed with no paid tiers, and the README stresses it is an independent utility not affiliated with, sponsored by, or endorsed by Google.
Why not just sign out and switch accounts inside Antigravity?Switching means restarting or swapping sessions; pgrav runs every account simultaneously in its own window, with fully separated cookies, local storage and chat histories so workspaces never contaminate each other.
Can a new profile reuse my existing settings, agent skills, and MCP tools?Yes — inherit from the host, which copies settings and snippets and links skills and MCP tools, or deep-clone another profile into an independent copy. Credentials, OAuth tokens and conversation histories are never copied or inherited.
Is there a GUI, or is everything done from the terminal?It is CLI-first, but a zero-dependency web console lets you manage instances visually, a compact floating HUD shows live status, and pgrav list --json gives machine-readable output for scripts and CI.
Will it eat RAM while sitting in the background?No — there is no background daemon and idle overhead is 0 MB; it is a pure Python 3 CLI that only acts when you run a command.
What are similar projects?Antigravity, opencode-antigravity-auth, Athena-Public, brig, google_workspace_mcp, open-swe, codeAgent, Baize
Which topics is it in?gemini-pro, multi-account, sandboxing, antigravity, ai-coding, google, oauth, sandbox, electron, gemini, coding-agent, desktop
Creator
edison-land
Size
0.5 MB
Stars
233
Updated
CommitSep 28Releasev1.2.0Sep 28
Age
25d
Commits · 90 Days