robbyt/codebase-analysis

Codebase Analysis via Google Antigravity (agy)

Use Google's Antigravity CLI for deep architectural analysis. agy is Google's agentic successor to gemini-cli and runs Google's Gemini models — it can roam the workspace, follow references, and surface structure that surface-level grep cannot.

Why --sandbox Here

Codebase analysis benefits from broad workspace access — agy needs to read many files, follow imports, and chase references. But it should not run arbitrary shell commands while doing so. Google Antigravity has no --allowed-tools flag, so use --sandbox to grant file access while denying shell execution:

agy --sandbox --print "..." --dangerously-skip-permissions

Pair --sandbox with a "Do not make any changes" clause for belt-and-suspenders safety.

Quick Start

agy --sandbox --print "Analyze this project's architecture. Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

When to Use

• Onboarding to unfamiliar codebases
• Understanding legacy systems
• Mapping component relationships
• Finding hidden dependencies
• Architecture documentation
• Technical debt assessment

Examples

Full project analysis:

agy --sandbox --print "Analyze this project. Report on:
- Overall architecture
- Key dependencies
- Component relationships
- Potential issues
Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

Flow mapping:

agy --sandbox --print "Map the authentication flow in this project. Identify all components involved. Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

Dependency analysis:

agy --sandbox --print "Analyze this project's dependencies:
- Direct vs transitive
- Outdated packages
- Circular dependencies
- Bundle size impact
Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

Technical debt:

agy --sandbox --print "Identify technical debt in this project:
- Deprecated patterns
- Inconsistent conventions
- Missing documentation
- Complex dependency chains
Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

Iterative Analysis

Use --continue (still inside --sandbox) for multi-turn investigation:

agy --sandbox --print "Analyze this project. Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

agy --continue --sandbox --print "What patterns did you find in the auth module? Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

agy --continue --sandbox --print "Are there security concerns with that pattern? Do not make any changes. Respond with analysis only." --dangerously-skip-permissions

Notes

• Google Antigravity must not make any changes; provide analysis ONLY. --sandbox blocks shell side-effects, but the prompt-level clause keeps it from editing files in the workspace.
• agy respects .gitignore — it cannot read files matching gitignore patterns.
• Can take 5–10 minutes for large codebases; bump --print-timeout to 10m or more for big jobs:

  agy --sandbox --print-timeout 10m --print "..." --dangerously-skip-permissions
  

• Requires sandbox bypass on the Bash tool: dangerouslyDisableSandbox: true (because Google Antigravity writes session state under ~/.gemini/, shared with the old gemini-cli).
• Use sessions for iterative exploration.
• See references/setup.md and references/patterns.md for more.