You open a fresh project in Antigravity and the status bar shows "Indexing… 12%" — and stays there for hours. Or worse, "Indexing complete" appears, but when you ask the agent to find a class under src/, it shrugs and says the file doesn't exist. I've hit this on new monorepos more than once, and every time it stops the day's work cold until I figure out what's going on.
Workspace Indexing is one of those quiet pieces of plumbing that holds up Antigravity's entire AI experience. When it jams, you get cascading symptoms that look unrelated at first glance: tab completions get worse, symbol search returns nothing, and the agent starts answering as if it has never seen the project structure. Worse, the symptoms don't say "indexing is broken" — they just look like the AI got dumber overnight, which is the kind of failure mode that erodes trust in the tool fast. This guide walks through the diagnostic flow I actually use, starting from the lightest fixes before reaching for anything destructive.
Sort the symptom into one of three patterns
Before you go reaching for rm -rf, figure out which pattern you're actually dealing with. Picking the wrong one wastes a lot of time, and a couple of these have very different fixes that look superficially similar.
Pattern A — Indexing never starts, or stays at 0%
The status bar reads "Indexing 0%" but neither CPU nor disk I/O is moving. The likely culprit is that the indexer process can't start, or that the .antigravity/index/ directory has broken permissions. You'll usually see this right after a fresh install, after restoring a home folder from backup, or after running Antigravity once with elevated privileges.
Pattern B — Progress climbs, then freezes
You see the meter cross 20%, maybe 40%, then stop. Most of the time, this is because a giant file (a generated GraphQL schema, a binary blob, an unwisely committed node_modules) has been included in the index, or because a parser is looping on a malformed file. CPU often pegs to 100% on one core in this scenario, even though the meter looks idle.
Pattern C — "Indexing complete," but the agent acts blind
The status reads complete, but when you ask about an existing function like getUserById, the agent says it can't find it. The index was built, but either the in-memory cache wasn't refreshed, or the session is reading an older index belonging to a different workspace with the same name. This pattern is the most confusing because the UI insists everything is fine.
Pattern A: when the indexer won't start at all
The first thing to check is whether Antigravity can actually write to its working directory. Look at the permissions under ~/.antigravity/index/{workspace-id}/.
# macOS / Linux — check ownership and permissions
ls -la ~/.antigravity/index/
# Drill into the directory for the active workspace
WORKSPACE_ID=$(cat ~/.antigravity/state/active-workspace.json | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
ls -la ~/.antigravity/index/${WORKSPACE_ID}/
# Expected: drwxr-xr-x 10 yourname staff 320 Apr 25 18:00 .You want to see your own user as the owner with write permission (u+w). If the directory is owned by root, or marked read-only, that's your problem. I once launched Antigravity under sudo for a single command (a mistake), and ever since that machine inherited root-owned index folders. The fix is straightforward:
# Restore ownership to your user (use admin/staff/your group on macOS)
sudo chown -R $(whoami):staff ~/.antigravity/index/
# Re-grant write permission, just in case
chmod -R u+w ~/.antigravity/index/If permissions look correct but indexing still won't kick off, fully quit Antigravity and remove ~/.antigravity/state/indexer.lock. When Antigravity exits abnormally, that lock file is sometimes left behind, and the next launch incorrectly assumes the indexer is already running. Make sure no Antigravity processes are still alive (ps aux | grep antigravity) before you delete the lock — otherwise you'll create the same problem on the next run.
Pattern B: when progress freezes mid-way
In my experience, eight out of ten cases here come down to "a huge file got swept into the index." Antigravity's defaults exclude obvious things like node_modules, .git, and dist/, but if your project keeps build artifacts, generated code, or large media in the project root, those get scanned by default. The pain is proportional to repository size: on a small app you might never notice, but on a Next.js monorepo with bundled outputs and AI-generated SDKs, the index can balloon to 50,000 files when only 2,000 of them matter.
Add an explicit .antigravityignore at the repo root:
# .antigravityignore — place at the project root
# Build artifacts
build/
out/
*.bundle.js
*.min.js
# Large generated files
**/*.generated.ts
**/openapi-types.ts
# Media and data
*.png
*.jpg
*.mp4
*.csv
*.parquet
# Vendored code
vendor/
third_party/Once the file is in place, run Workspace: Rebuild Index from the command palette (Cmd + Shift + P). Most freezes resolve here because the file count drops by an order of magnitude, and the parser stops choking on multi-megabyte minified bundles.
If indexing still hangs, the parser might be choking on one specific file. Check the indexer log to find what was processed last:
# The last 30 lines usually tell you where the indexer got stuck
tail -30 ~/.antigravity/logs/indexer.log
# If you see "Parsing file: …" frozen for minutes, that file is the suspect
# Example: Parsing file: src/generated/schema.graphql.ts (8.2MB)In my case, an 8 MB auto-generated GraphQL schema was eating all the parser's memory. Adding it to .antigravityignore solved the problem instantly. Generated files almost never repay the cost of indexing them — the agent rarely needs to navigate inside them — so excluding them up front is a good habit, not just a fix.
Pattern C: when "complete" doesn't mean visible
This pattern is usually about a stale in-memory cache rather than a missing index. Before you restart Antigravity entirely, try Workspace: Reload Index Cache from the command palette. That refreshes only the in-memory layer, which is faster and avoids losing your editor state.
If that doesn't help, check for workspace ID collisions. When you open two projects with the same folder name in different locations, internal IDs can clash and the session ends up reading the older project's index.
# List all workspaces
ls ~/.antigravity/workspaces/
# Find duplicates by base name
ls ~/.antigravity/workspaces/ | sort | awk -F'-' '{print $1}' | sort | uniq -c | sort -rn | head
# Example: " 3 my-app" means three workspaces share the base nameIf you see duplicates, delete the inactive ones or rename them to something distinct. I cover the broader topic of context drift and stale references in the AI suggestion quality diagnostic guide, but workspace ID collision is a particularly sneaky cause because nothing in the UI tells you it's happening — the agent just answers as if your code were a different code.
Hardening settings for large repositories
If a project keeps biting you with indexing problems, lock in some defensive settings up front. Edit ~/.antigravity/settings.json and adjust:
"indexing.maxFileSize": maximum bytes per file. The default of 5 MB is generous; on projects with lots of generated code, dropping to 1 MB stabilizes things considerably"indexing.parallelism": how many files are parsed in parallel. Default is 4, but on slower CPUs, 2 actually feels faster because there's less swapping"indexing.includeSymbolsOnly": a lighter mode that indexes symbol metadata only. Useful for read-mostly workspaces where you don't need full-text search
For a monorepo with 300,000 files I'm working on, this combination is what holds up under daily use:
{
"indexing": {
"maxFileSize": 1048576,
"parallelism": 6,
"includeSymbolsOnly": false,
"excludeBinaries": true
}
}For the bigger picture on managing context across enormous codebases, see the large codebase context management guide. Reading that after the fix here helps prevent the next round of indexing pain rather than just patching the current one.
The single move that fixes most cases
If you take only one thing away: when the symptoms are unclear and you don't know which pattern you're in, just run Workspace: Rebuild Index from the command palette. About nine out of ten indexing problems clear up there. The deeper diagnostics in this guide are for the remaining ten percent — stubborn cases where the cheap fix doesn't stick.
Workspace Indexing is plumbing you don't think about until it breaks — and once it breaks, your trust in the whole AI experience wobbles fast. The next time the agent goes weirdly off-target during your day, glance at the indexing status before anything else. Catching the cause there moves the diagnosis forward several steps in one motion, and it costs nothing more than a glance at the status bar.