◉ANTIGRAVITY LABJP
Articles/Antigravity Basics
◉ Antigravity Basics/2026-04-24Intermediate

When Antigravity's Built-in Terminal Won't Start or Commands Fail: A Layered Diagnostic Guide

When the Antigravity terminal panel won't open, stays unresponsive, or can't find your commands, the fix depends on which layer actually broke. This guide splits the symptoms into three patterns and walks through each recovery path.

antigravity429terminal4troubleshooting105diagnosticshell

The single most disruptive moment in using Antigravity is the one when the built-in terminal goes silent. Your agent is about to run npm install, and the panel refuses to open. Or the panel is right there, but typing node -v produces nothing. I hit this on day one of spinning up a Next.js 16 project in Antigravity, and I burned two hours chasing the wrong layer before I realized why.

Here is the trap: the symptoms look similar, but the root causes live on completely different layers. "Won't open" and "opens but frozen" and "opens but commands are missing" are three separate problems with three separate fixes. This guide is the three-layer triage flow I wish I had that first day. It takes you from "a clean restart fixed it" to "your $PATH is wrong at the process-boundary level," step by step.

Step one: classify which of the three patterns you are in

Half of the time spent debugging terminal issues is spent working on the wrong layer. The first 30 seconds should go into identifying which of these three shapes your problem has.

  • Pattern A — the terminal panel itself will not appear: You press Ctrl+ backtick, or pick "New Terminal" from the menu, and nothing happens. Or the panel flashes and disappears. This is an Electron renderer issue or a ptyHost process failing to spawn.
  • Pattern B — the panel appears but no prompt shows up: The terminal panel is visible, but there is no $ or % prompt. You see a cursor blinking and nothing else. The shell process started, but it is stuck somewhere in the login profile.
  • Pattern C — prompt works but commands are not found: You see node: command not found or git: command not found. The shell is alive, but your environment variables, especially $PATH, are not what you expect.

Confusing these three means running fixes that were never going to help. Once you know which pattern you have, you only need to read the matching section below.

Pattern A: when the terminal panel refuses to open

When the panel itself does not appear, the fastest move is to open Antigravity's developer tools. Go to Help → Toggle Developer Tools, switch to the Console tab, and scan for red errors.

You will most often see Unable to start pty host process or spawn /bin/bash ENOENT. These mean Antigravity is trying to launch a shell at a path that no longer exists on the OS side.

Here is the fix order I follow, in priority:

  1. Fully quit Antigravity and relaunch it: Just closing the window sometimes leaves the ptyHost process running. On macOS, use Cmd+Q. On Windows, check Task Manager and kill any lingering antigravity.exe.
  2. Remove any user-level shell path override: If your settings.json contains "terminal.integrated.defaultProfile.osx" or similar, delete it temporarily and fall back to the default. A broken profile definition is a surprisingly common cause.
  3. Confirm the shell actually exists on disk: The terminal is just spawning a shell binary. Open a different terminal app and run ls -la /bin/zsh /bin/bash /opt/homebrew/bin/fish. If you reinstalled a shell via Homebrew, the binary likely moved to /opt/homebrew/bin/, and a stale /usr/local/bin/ reference will hit ENOENT.
  4. Last resort: reload with extensions disabled: Run Developer: Reload With Extensions Disabled from the command palette. Extensions that touch the terminal layer (ShellLauncher-style extensions, Remote Development extensions) are sometimes the culprit.

In my experience, around 80% of "won't open" issues resolve within those four steps. The remaining 20% are cases where the OS upgraded the shell underneath Antigravity, and you need to combine this with the Pattern B instructions below.

Pattern B: when the panel opens but hangs before the prompt

A panel that appears but never prompts is almost always a shell login profile that has stalled, usually waiting on an external command that never returns.

The first place to look is your ~/.zshrc or ~/.bashrc. Specifically, any line that calls out to the network at startup: things like nvm use default, pyenv init -, or a custom script that fetches environment variables from a secrets service. When the network is flaky, any of these can block for 30 seconds or more.

Profile the startup cost

Run this in a different terminal (your OS's stock terminal app) to see where your shell is spending time:

# Goal: find which lines of zsh startup are consuming wall-clock time
# Requires: zsh is your default shell, ~/.zshrc exists
zsh -xvs 2>&1 | ts '[%H:%M:%.S]' | head -100

If ts is not installed, grab it with brew install moreutils. Any row where the timestamp jumps forward by more than a second is a suspect. In most cases, the offender is nvm.sh sourcing, or rbenv init evaluating on every shell start.

A quick bypass and a permanent fix

For an emergency bypass, edit "terminal.integrated.profiles.osx" in Antigravity and add "args": ["-l", "-i", "--no-rcs"] to your shell entry. This starts the shell without sourcing the profile. The cost is that your PATH will not be what you expect, so treat it as a temporary patch, not a solution.

The real fix is to restructure .zshrc to lazy-load the expensive parts. Use zsh-defer or similar lazy-load helpers so that nvm.sh only runs the first time you actually call node. On my machine this cut shell startup from around 4 seconds to under 300 milliseconds.

Pattern C: when commands work nowhere, not even the ones that "should just be there"

If the terminal runs fine but node: command not found keeps greeting you, the cause is usually that Antigravity, launched from the GUI, inherited a different $PATH than your regular terminal.

This is especially common on macOS with Homebrew. Antigravity launched from Finder or Spotlight often does not see /opt/homebrew/bin. If launching from the command line with open -a Antigravity works but double-clicking the Dock icon does not, you are in this situation.

See exactly what your PATH is

Run this inside the Antigravity terminal to list each entry on its own line:

# Goal: print the current PATH one entry per line so differences are easy to spot
# Expected output: each directory on its own line; confirm /opt/homebrew/bin is present
echo "$PATH" | tr ':' '\n'

If neither /opt/homebrew/bin (Apple Silicon) nor /usr/local/bin (Intel Mac) is present, your Homebrew-installed tools are invisible to this shell.

Two ways to fix it permanently

You have two clean options. I switch between them depending on the project:

  • Option 1 — set PATH in Antigravity's settings: Add "PATH": "/opt/homebrew/bin:/usr/local/bin:${env:PATH}" under "terminal.integrated.env.osx" in settings.json. Fast, but awkward if different projects need different Node versions.
  • Option 2 — fix it in .zprofile: This is the one I recommend. Add a single line to ~/.zprofile: eval "$(/opt/homebrew/bin/brew shellenv)". Since .zprofile is read by login shells, GUI-launched processes see the right PATH too, and there is no per-terminal cost.

On Windows, if you see the same shape of symptom, set your PATH in the System environment variables rather than User, then restart Antigravity fully. User-level variables sometimes fail to propagate to the Antigravity launcher process.

Last resort: reset just the terminal configuration without touching the rest

If none of the three pattern fixes worked, the cleanest rescue is to reset only the terminal-related configuration. You do not need to reinstall Antigravity to do this.

Quit Antigravity, then back up and prune only the terminal keys from settings.json. On macOS:

# Goal: back up settings.json and remove only terminal.* keys
# Requires: Antigravity fully quit before running
cd ~/Library/Application\ Support/Antigravity/User
cp settings.json settings.json.backup
python3 -c "
import json
with open('settings.json') as f:
    data = json.load(f)
cleaned = {k: v for k, v in data.items() if not k.startswith('terminal.integrated.')}
with open('settings.json', 'w') as f:
    json.dump(cleaned, f, indent=2)
print(f'removed {len(data) - len(cleaned)} terminal keys')
"

Relaunch Antigravity. You should get a terminal on default settings. Once it is stable, restore settings from the backup one at a time until you find the specific key that was breaking things.

Using exactly this approach I once isolated terminal.integrated.persistentSessionReviveProcess as the problem setting after an Antigravity update changed how persistent sessions are restored. Settings that worked for months can suddenly turn into landmines after the editor updates its internals.

What to do next

Terminal plumbing is one of those layers you stop thinking about until it breaks, and then it takes your whole day. Before you close this article, spend one minute measuring how long your own shell takes to start. Run zsh -xvs as shown above. If any single line takes more than two seconds, that line is a future incident waiting to happen, and you have the chance to defuse it now.

If you are working through related issues, these companion articles may help:

Share

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

◉ Antigravity2026-05-25
Why Antigravity Agents Hang on ssh, sudo, and git rebase -i — Diagnosing and Permanently Fixing the Missing TTY Problem
When you ask an Antigravity agent to deploy, the terminal panel stops on 'password:' and never moves. The agent isn't broken — the shell behind it has no PTY, so interactive prompts have no one to answer them. Here's how to diagnose and remove every interactive command from your agent workflow.
◉ Antigravity2026-05-31
Why Your Antigravity Agent Stops Mid-Task with 429 RESOURCE_EXHAUSTED, and How to Fix It
When you hand a long task to an Antigravity agent, it sometimes halts halfway with a red 429 RESOURCE_EXHAUSTED. That is a rate-limit or quota signal, not a bug. Here is how I diagnose the three flavors of 429 in production, and how to keep your agent from stalling on the same wall twice.
◉ Antigravity2026-05-28
Fixing Antigravity Google Sign-in That Won't Return From the Browser
When you press Sign in with Google in Antigravity and the browser just hangs without returning to the editor, the cause is rarely a single thing. Here is how I narrow it down across four layers — callback port, third-party cookies, stale session files, and network path — using only commands I keep close on every machine.
📚RECOMMENDED BOOKS
Build a Large Language Model (From Scratch)
Sebastian Raschka
LLM Dev
Prompt Engineering for LLMs
Berryman & Ziegler
Prompting
AI Engineering
Chip Huyen
AI Eng
* Contains affiliate links
See all →