Home / Documentation

Documentation

Version 5.3.2 · Last updated 21 October 2026

Antigravity Codespaces Pro is a free, MIT-licensed extension that connects VS Code-based editors such as Cursor and Google Antigravity to GitHub Codespaces over SSH using the GitHub CLI.

Overview

Antigravity Codespaces Pro is an open-source extension that lets you list, start, stop and connect to GitHub Codespaces from VS Code-based editors such as Google Antigravity, Cursor, VS Code, Windsurf and VSCodium. Your editor stays on your machine and the codespace runs on GitHub. The connection is an ordinary SSH session tunnelled through the official GitHub CLI, so there are no keys to manage and no ports to open.

The extension does not host anything, does not proxy your traffic through a third party, and does not include AI models. It manages the remote environment; you bring the editor and the tools.

Requirements

• An editor compatible with VS Code engine ^1.85.0.
• The GitHub CLI (gh).
• An OpenSSH client (ssh -V should print a version).
• A Remote-SSH extension that suits your editor. See the table below.
• A GitHub account that can create codespaces.

Install

Per-editor steps, OS notes and sources are in the IDE setup guide. See also the guides for Cursor, Antigravity and Windsurf, and the Remote-SSH comparison.

# Open VSX editors (replace cursor with antigravity, windsurf, codium…)
cursor --install-extension nirbhay-hiwse.antigravity-codespaces
# VS Code, from the downloaded release file
code --install-extension antigravity-codespaces-5.3.2.vsix

Sign in and scopes

Connecting needs a gh token with the codespace scope. Usage analytics additionally need the user scope, because GitHub's billing API requires it. You can skip the second one if you do not want analytics.

gh auth login -s codespace
# already signed in, scope missing
gh auth refresh -h github.com -s codespace
# optional, for usage analytics
gh auth refresh -h github.com -s user

Before every Connect, Quick Connect and Test SSH, a shared preflight checks four states: gh missing, signed out, scope missing, and the wrong user active. Each one gets its own fix button rather than a generic SSH error.

Cloud Hub

Run Open Cloud Hub Dashboard. Every codespace appears as a card in grid view or as a row in list view, with its state, repository, branch, machine type and owning account. A usage card sits above the grid when analytics are available. A first-run card walks new users through signing in, installing gh and connecting, and it disappears after the first successful connection.

Quick Connect

Press Alt+C or run Quick Connect to Codespace..., pick a codespace and it opens in a new window. If the codespace is stopped, start it first. Reconnect to Last Codespace reopens the one you used most recently. When connecting, the extension looks up the real workspace folder from your recent folders or the dev container metadata, and only falls back to defaultRemoteFolder.

Codespace actions

From a card, the sidebar or the Quick Actions menu you can Turn ON, Stop, Rebuild Container, Delete, Open in Browser and Copy SSH Command, and you can Create New Codespace. Deleting is permanent and removes uncommitted work in that codespace, so push first.

Multiple accounts

The extension reads every account signed in to gh. Switch GitHub Account changes the active one, and the hub, the SSH hosts and the usage numbers follow it. Scope checks read the block for the exact account, so one account's scopes are never mistaken for another's.

Forwarded ports

Ports a codespace exposes are listed under it. Open Port in Browser opens one directly.

Usage analytics

Since 5.2.0 the Cloud Hub and the sidebar show Codespaces usage for the active gh account, read from GitHub's billing API (the usage summary and daily usage). The numbers match github.com/settings/billing. Compute is measured in core-hours and storage in GB-month. They are separate quotas and are never added together.

A 4-core machine uses quota twice as fast as a 2-core machine: one hour on it is four core-hours. Bars turn orange at 75% and red at 90%. Source for quotas: GitHub Docs.

The card can be in one of five states: live numbers, needs permission (missing user scope), billed to an organization, unavailable with the reason, or offline with the last good numbers. It never shows an estimate in place of missing data.

SSH configuration

The extension writes one clearly marked block per codespace into ~/.ssh/config, between # CS_ENTRY:<name> and # END_CS_ENTRY:<name>. Nothing outside those markers is touched. Every change is logged in the Codespaces output channel.

Host cs.<name>
  User codespace
  ProxyCommand "<path-to-gh>" cs ssh -c "<name>" --stdio
  StrictHostKeyChecking accept-new
  ServerAliveInterval 30
  ServerAliveCountMax 10

Run Sync SSH Config to regenerate the blocks and Test SSH Connectivity to check the tunnel without opening a window.

Keepalive for long agent sessions

AI agents often run for many minutes with no keyboard input, which is when idle connections tend to drop. The defaults send a keepalive every 30 seconds and give up after 10 missed replies. Raise them in settings if your network is unreliable. Keepalive keeps the SSH tunnel open; it does not stop GitHub from stopping a codespace after its own idle timeout, which you set in GitHub's Codespaces settings.

Setup Doctor

Codespaces: Setup Doctor checks that gh is installed and signed in, that the token has the right scopes, that an OpenSSH client and a Remote-SSH extension are present, that remote.SSH.remotePlatform is correct and that the SSH config has no duplicate codespace blocks. Every failed check has a one-click fix. It can also produce a diagnostic report for an issue, with GitHub tokens (gho_, ghu_, ghs_, ghr_, ghp_) redacted automatically.

Settings

All 14 settings use the prefix antigravity-codespaces. Defaults and descriptions are taken from package.json in version 5.3.2.

Security and privacy

• Authentication uses gh and the IDE's built-in GitHub sign-in. A personal access token, if you paste one, is kept in the IDE's SecretStorage.
• Host keys are pinned on first use in ~/.antigravity-codespaces/known_hosts; a changed key is rejected and reported.
• No tokens or secrets are written to logs.
• The extension talks only to GitHub. There is no telemetry server.

Limitations

• Organization-owned codespaces have no free quota; their usage appears as “Billed to {org}”.
• The VS Code Marketplace lists 4.3.0; 5.3.2 is on Open VSX and as a .vsix.
• Editors that cannot open vscode-remote://ssh-remote+ windows need a manual connection with Copy SSH Command.
• Browser-based IDEs such as Eclipse Theia or OpenVSCode Server are not supported, because they have no local SSH client.

Errors and alerts

GitHub API and connection messages (5.3.1 and later)

Every GitHub API request has a 15-second timeout. When GitHub answers with a 5xx server error, the extension waits 5 seconds and retries once before it shows a message. Each message states what happened and why, and offers the buttons listed below.

Listing, starting, stopping, creating and deleting codespaces treat a 429 response, or a 403 response with x-ratelimit-remaining: 0, as a rate limit rather than a missing permission. Every rate-limit message in 5.3.2 uses the same wording: “GitHub API rate limit reached. Resets at HH:MM.” when GitHub sends a reset time, and “GitHub API rate limit reached. Try again in a few minutes.” when it does not.

A failed connect shows Couldn't open <codespace> in this IDE. with Run Setup Doctor, Copy SSH command and Details, and the card returns to its real state instead of showing “Connected”.

Usage card messages (5.3.1 and later)

• Rate limit: when the billing API answers 429, or 403 with x-ratelimit-remaining: 0, the card shows the same message: “GitHub API rate limit reached. Resets at HH:MM.”, or “GitHub API rate limit reached. Try again in a few minutes.” when there is no reset time.
• Unexpected response: if the billing API returns data this version cannot read, the card shows Usage data unavailable (unexpected response). with the explanation “GitHub returned usage data in a format this version doesn't recognise.” and the buttons Retry and Details. It never shows 0 or a made-up figure in that case.
• Last good data: when GitHub billing cannot be reached, the Cloud Hub keeps the last numbers and shows Usage is from the last successful refresh. with the time of that refresh.

Alert levels and panel states

Messages use four levels. Error (critical) shows a notification and a red banner. Warning shows an amber banner without a popup. Info uses the status bar or a quiet notification. Silent is written to the log only. Banners carry a text label as well as a colour, and a dismissed banner returns on the next refresh if the problem is still there.

The Cloud Hub has five panel states: loading (skeleton cards), empty (“No codespaces yet.” with a create button), signed out (a single sign-in card), error with cached data (a banner reading “Showing data as of <time>.”, with each card tagged “Cached”, dimmed, and its actions disabled until a refresh succeeds), and partial (a banner for each account that failed to load, with Retry). The sidebar follows the same rules: cached cards are tagged, dimmed and disabled, and the signed-out sidebar shows a single card, “Sign in with the GitHub CLI to see and open your codespaces.”, with a Sign in with gh button. If the GitHub CLI is not found, the sidebar instead shows the card “GitHub CLI isn't installed.” Its Install GitHub CLI button opens cli.github.com, and two links follow: “Use a personal access token instead” and “I've installed it, check again”.

Other messages

Every message below is produced by the extension's own code. Where a fix can be automated, the message carries a button for it.

Commands

The extension contributes 21 commands. Run them from the Command Palette. Quick Connect is also bound to Alt+C.

• Open Cloud Hub Dashboard
• Quick Connect to Codespace...
• Open Quick Actions Menu
• Test SSH Connectivity
• Refresh
• Switch GitHub Account
• Create New Codespace
• Sync SSH Config
• Connect
• Turn ON
• Stop
• Rebuild Container
• Open in Browser
• Copy SSH Command
• Delete Codespace
• Open Port in Browser
• Login to GitHub Account
• Codespaces: Setup Doctor
• Reconnect to Last Codespace
• Codespaces: Refresh Usage
• Codespaces: Grant Usage Access (gh user scope)

Getting help

Run Setup Doctor, copy its report, and open an issue with what you did, what you expected and what happened. Check the report for anything personal before you post it.