Skip to content

study8677/antigravity-workspace-template

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

175 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Antigravity Workspace

AI Workspace Template

Multi-agent knowledge engine for any codebase.

ag-refresh builds a knowledge base. ag-ask answers questions. Any LLM, any IDE.

Language: English | δΈ­ζ–‡ | EspaΓ±ol

License Python CI DeepWiki


Cursor Claude Code Windsurf Gemini CLI VS Code Codex Cline Aider

Before vs After Antigravity

Why Antigravity?

An AI Agent's capability ceiling = the quality of context it can read.

The engine is the core: ag-refresh deploys a multi-agent cluster that autonomously reads your code β€” each module gets its own Agent that generates a knowledge doc. ag-ask routes questions to the right Agent, grounded in real code with file paths and line numbers.

Instead of handing Claude Code / Codex a repo-wide grep and making it hunt on its own, give it a ChatGPT for your repository.

Tested on OpenClaw (12K files, 348K stars) with MiniMax2.7 β€” module Q&A scored 10/10, 111 modules self-learned in 43 minutes. See full eval below.

Traditional approach:              Antigravity approach:
  CLAUDE.md = 5000 lines of docs     Claude Code calls ask_project("how does auth work?")
  Agent reads it all, forgets most   Router β†’ ModuleAgent reads actual source, returns exact answer
  Hallucination rate stays high      Grounded in real code, file paths, and git history
Problem Without Antigravity With Antigravity
Agent forgets coding style Repeats the same corrections Reads .antigravity/conventions.md β€” gets it right the first time
Onboarding a new codebase Agent guesses at architecture ag-refresh β†’ ModuleAgents self-learn each module
Switching between IDEs Different rules everywhere One .antigravity/ folder β€” every IDE reads it
Asking "how does X work?" Agent reads random files ask_project MCP β†’ Router routes to the responsible ModuleAgent

Architecture is files + a live Q&A engine, not plugins. Portable across any IDE, any LLM, zero vendor lock-in.


Quick Start

Option A β€” Engine: multi-agent Q&A on your codebase (recommended)

# 1. Install engine + CLI
pip install "git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=cli"
pip install "git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=engine"

# 2. Configure .env with any OpenAI-compatible API key
cd my-project
cat > .env <<EOF
OPENAI_BASE_URL=https://your-endpoint/v1
OPENAI_API_KEY=your-key
OPENAI_MODEL=your-model
AG_ASK_TIMEOUT_SECONDS=120
EOF

# 3. Build knowledge base (ModuleAgents self-learn each module)
ag-refresh --workspace .

# 4. Ask anything
ag-ask "How does auth work in this project?"

# 5. (Optional) Register as MCP server for Claude Code
claude mcp add antigravity ag-mcp -- --workspace $(pwd)

Option B β€” Context files only (any IDE, no LLM needed)

pip install git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=cli
ag init my-project && cd my-project
# IDE entry files bootstrap into AGENTS.md; dynamic knowledge is in .antigravity/

Features at a Glance

  ag init             Inject context files into any project (--force to overwrite)
       β”‚
       β–Ό
  .antigravity/       Shared knowledge base β€” every IDE reads from here
       β”‚
       β”œβ”€β”€β–Ί ag-refresh     Dynamic multi-agent self-learning β†’ module knowledge docs + structure map
       β”œβ”€β”€β–Ί ag-ask         Router β†’ ModuleAgent Q&A with live code evidence
       └──► ag-mcp         MCP server β†’ Claude Code calls directly

Dynamic Multi-Agent Cluster β€” During ag-refresh, the engine uses smart functional grouping: files are grouped by import relationships, directory co-location, and filename prefixes. Source code is pre-loaded directly into agent context (no tool calls needed), and build artifacts are automatically filtered out. Each sub-agent analyzes ~30K tokens of focused, functionally related code in a single LLM call and outputs a comprehensive Markdown knowledge document (agents/*.md). For large modules, multiple sub-agents run in parallel β€” each produces its own agent.md (no merging, no information loss). A Map Agent reads all agent docs and generates map.md β€” a routing index. During ag-ask, Router reads map.md to select relevant modules, then feeds their agent docs to answer agents. For structural questions (call chains, dependencies, impact analysis), the Router automatically queries GitNexus code graph for precise relationships. Fully language-agnostic β€” module detection uses pure directory structure, code analysis is done entirely by LLMs. Works with any programming language.

GitAgent β€” A dedicated agent for analyzing git history β€” understands who changed what and why.

GitNexus Graph Enrichment (optional) β€” Install GitNexus to auto-unlock graph-enriched answers. The Router LLM decides when a question needs structural analysis (call chains, dependencies, impact) and queries GitNexus automatically β€” combining precise graph data with semantic understanding from agent docs.


CLI Commands

Command What it does LLM needed?
ag init <dir> Inject cognitive architecture templates No
ag init <dir> --force Re-inject, overwriting existing files No
ag refresh --workspace <dir> CLI convenience wrapper around the knowledge-hub refresh pipeline Yes
ag ask "question" --workspace <dir> CLI convenience wrapper around the routed project Q&A flow Yes
ag-refresh Multi-agent self-learning of codebase, generates module knowledge docs + conventions.md + structure.md Yes
ag-ask "question" Router β†’ ModuleAgent/GitAgent routed Q&A Yes
ag-mcp --workspace <dir> Start MCP server β€” exposes ask_project + refresh_project to Claude Code Yes
ag report "message" Log a finding to .antigravity/memory/ No
ag log-decision "what" "why" Log an architectural decision No

ag ask / ag refresh are available when both cli/ and engine/ are installed. ag-ask / ag-refresh are the engine-only entrypoints.


Two Packages, One Workflow

antigravity-workspace-template/
β”œβ”€β”€ cli/                     # ag CLI β€” lightweight, pip-installable
β”‚   └── templates/           # .cursorrules, CLAUDE.md, .antigravity/, ...
└── engine/                  # Multi-agent engine + Knowledge Hub
    └── antigravity_engine/
        β”œβ”€β”€ _cli_entry.py    # ag-ask / ag-refresh / ag-mcp + python -m dispatch
        β”œβ”€β”€ config.py        # Pydantic configuration
        β”œβ”€β”€ hub/             # β˜… Core: multi-agent cluster
        β”‚   β”œβ”€β”€ agents.py    #   Router + ModuleAgent + GitAgent
        β”‚   β”œβ”€β”€ contracts.py #   Pydantic models: claims, evidence, refresh status
        β”‚   β”œβ”€β”€ ask_pipeline.py    # agent.md + graph-enriched ask
        β”‚   β”œβ”€β”€ refresh_pipeline.py # LLM-driven refresh β†’ agents/*.md + map.md
        β”‚   β”œβ”€β”€ ask_tools.py
        β”‚   β”œβ”€β”€ scanner.py   #   multi-language project scanning
        β”‚   β”œβ”€β”€ module_grouping.py # smart functional file grouping
        β”‚   β”œβ”€β”€ structure.py
        β”‚   β”œβ”€β”€ knowledge_graph.py
        β”‚   β”œβ”€β”€ retrieval_graph.py
        β”‚   └── mcp_server.py
        β”œβ”€β”€ mcp_client.py    # MCP consumer (connects external tools)
        β”œβ”€β”€ memory.py        # Persistent interaction memory
        β”œβ”€β”€ tools/           # MCP query tools + extensions
        β”œβ”€β”€ skills/          # Skill loader
        └── sandbox/         # Code execution (local / microsandbox)

CLI (pip install .../cli) β€” Zero LLM deps. Injects templates, logs reports & decisions offline.

Engine (pip install .../engine) β€” Multi-agent runtime. Powers ag-ask, ag-refresh, ag-mcp. Supports Gemini, OpenAI, Ollama, or any OpenAI-compatible API.

New skill packaging updates:

  • engine/antigravity_engine/skills/graph-retrieval/ β€” graph-oriented retrieval tools for structure and call-path reasoning.
  • engine/antigravity_engine/skills/knowledge-layer/ β€” project knowledge-layer tools for semantic context consolidation.
# Install both for full experience
pip install "git+https://...#subdirectory=cli"
pip install "git+https://...#subdirectory=engine"

For local work on this repository itself:

python3 -m venv venv
source venv/bin/activate
pip install -e ./cli -e './engine[dev]'
pytest engine/tests cli/tests

How It Works

1. ag init β€” Inject context files

ag init my-project
# Already initialized? Use --force to overwrite:
ag init my-project --force

Creates AGENTS.md (authoritative behavior rules), IDE bootstrap files (.cursorrules, CLAUDE.md, .windsurfrules, .clinerules, .github/copilot-instructions.md), and .antigravity/ dynamic context files.

2. ag-refresh β€” Multi-agent self-learning

ag-refresh --workspace my-project

9-step pipeline:

  1. Scan codebase (languages, frameworks, structure)
  2. Multi-agent pipeline generates conventions.md
  3. Generate structure.md β€” language-agnostic file tree with line counts
  4. Build knowledge graph (knowledge_graph.json + mermaid)
  5. Write document/data/media indexes
  6. LLM full-context analysis β€” group files by import graph + directory + prefix, pre-load into context (~30K tokens per sub-agent), filter out build artifacts. Each sub-agent reads the full source code and outputs a comprehensive Markdown knowledge document (agents/*.md). Large modules get multiple agent docs (one per group, no merging). Global API concurrency control prevents rate-limiting. Fully language-agnostic β€” works with any programming language.
  7. RefreshGitAgent analyzes git history, generates _git_insights.md
  8. Map Agent reads all agent docs β†’ generates map.md (module routing index with descriptions and key topics)
  9. GitNexus indexing (optional) β€” runs gitnexus analyze to build a Tree-sitter code graph (16 languages, call chains, dependencies). Auto-skipped if GitNexus is not installed.

3. ag-ask β€” Router-based Q&A

ag-ask "How does auth work in this project?"

The ask pipeline uses a dual-path architecture:

  • Semantic path: Router reads map.md β†’ selects modules β†’ reads agents/*.md β†’ LLM answers with code references. Multiple agent docs are read in parallel, then a Synthesizer combines answers.
  • Graph path (automatic): Router LLM decides if the question needs structural analysis β†’ queries GitNexus for call chains, dependencies, or impact β†’ injects graph data into the answer context. Silently skipped if GitNexus is not installed.

Falls back to the legacy Router β†’ ModuleAgent/GitAgent swarm when agent docs are not yet generated.


IDE Compatibility

Architecture is encoded in files β€” any agent that reads project files benefits:

IDE Config File
Cursor .cursorrules
Claude Code CLAUDE.md
Windsurf .windsurfrules
VS Code + Copilot .github/copilot-instructions.md
Gemini CLI / Codex AGENTS.md
Cline .clinerules
Google Antigravity .antigravity/rules.md

All are generated by ag init: AGENTS.md is the single behavioral rulebook, IDE-specific files are thin bootstraps, and .antigravity/ stores shared dynamic project context.


Advanced Features

MCP Server β€” Give Claude Code a ChatGPT for your codebase

Instead of reading hundreds of documentation files, Claude Code can call ask_project as a live tool β€” backed by a dynamic multi-agent cluster: Router routes questions to the right ModuleAgent, returning grounded answers with file paths and line numbers.

Setup:

# Install engine
pip install "git+https://github.com/study8677/antigravity-workspace-template.git#subdirectory=engine"

# Refresh knowledge base first (ModuleAgents self-learn each module)
ag-refresh --workspace /path/to/project

# Register as MCP server in Claude Code
claude mcp add antigravity ag-mcp -- --workspace /path/to/project

Tools exposed to Claude Code:

Tool What it does
ask_project(question) Router β†’ ModuleAgent/GitAgent answers codebase questions. Returns file paths + line numbers.
refresh_project(quick?) Rebuild knowledge base after significant changes. ModuleAgents re-learn the code.
Dynamic Multi-Agent Cluster β€” Module-level self-learning + intelligent routing

The engine's core is a dynamically created Agent cluster per code module:

 ag-refresh:                                 ag-ask:

 For each module:                            Router (reads map.md)
 β”Œ Group files by import graph                 β”œβ”€β”€ GRAPH: no β†’ read agents/*.md β†’ LLM answer
 β”œ Pre-load ~30K tokens per sub-agent          └── GRAPH: yes β†’ query GitNexus graph
 β”œ Filter out build artifacts                        β†’ graph data + agents/*.md β†’ LLM answer
 β”œ Sub-agents β†’ Markdown agent docs
 β”œ agents/{module}.md (or /group_N.md)
 β”œ Map Agent β†’ map.md
 β”” GitNexus analyze (optional)

Key innovations:

  • LLM as analyzer: No AST parsing or regex β€” source code is fed directly to LLMs for analysis. Works with any programming language out of the box.
  • Smart grouping: Files grouped by import relationships, directory co-location, and filename prefixes. Build artifacts automatically filtered out. Hard character limit (800K) prevents context overflow.
  • No information loss: Large modules produce multiple agent.md files (one per group) β€” no merging or compression. During ag-ask, multiple agent docs are read by parallel LLM calls, then a Synthesizer combines answers.
  • Graph-enriched answers: Router LLM automatically decides when a question needs structural data (call chains, dependencies, impact) and queries GitNexus. Combines precise graph relationships with semantic understanding.
  • Global API concurrency control: AG_API_CONCURRENCY limits total simultaneous LLM calls across all modules, preventing rate-limiting.
  • Language-agnostic module detection: Pure directory structure β€” no __init__.py or any language-specific marker required.
# ModuleAgents self-learn your codebase
ag-refresh

# Only scan files changed since last refresh
ag-refresh --quick

# Router intelligently routes to the right ModuleAgent
ag-ask "What testing patterns does this project use?"

# Log findings and decisions (no LLM needed)
ag report "Auth module needs refactoring"
ag log-decision "Use PostgreSQL" "Team has deep expertise"

Works with Gemini, OpenAI, Ollama, or any OpenAI-compatible endpoint. Powered by OpenAI Agent SDK + LiteLLM.

MCP Integration (Consumer) β€” Let agents call external tools

MCPClientManager lets your agents connect to external MCP servers (GitHub, databases, etc.), auto-discovering and registering tools.

// mcp_servers.json
{
  "servers": [
    {
      "name": "github",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "enabled": true
    }
  ]
}

Set MCP_ENABLED=true in .env.

GitNexus Graph Enrichment β€” Automatic structural intelligence for ask queries

GitNexus builds a code knowledge graph using Tree-sitter AST parsing (16 languages). When installed, Antigravity integrates it at two levels:

1. Refresh-time indexing β€” ag-refresh automatically runs gitnexus analyze (Step 9) to build/update the code graph. Skipped silently if GitNexus is not installed.

2. Ask-time graph enrichment β€” The Router LLM decides whether a question needs structural analysis:

  • "What does the auth module do?" β†’ GRAPH: no β†’ pure agent.md answer
  • "Who calls handleLogin?" β†’ GRAPH: yes β†’ queries GitNexus β†’ graph data + agent.md β†’ enriched answer
User: "What functions call the send method in gateway?"

Router: MODULES: gateway, tests_gateway | GRAPH: yes
  β†’ GitNexus query returns call chains with confidence scores
  β†’ Agent docs provide semantic context (what each caller does)
  β†’ Combined answer: precise call chain + file paths + line numbers + purpose
Capability What it provides
gitnexus_query Hybrid search (BM25 + semantic) β€” execution flows, not just files
gitnexus_context 360-degree symbol view: callers, callees, references, definition
gitnexus_impact Blast radius analysis β€” what breaks if you change a symbol?

Note: GitNexus is NOT bundled with Antigravity. It requires separate installation via npm (npm install -g gitnexus). Antigravity works fully without it β€” when not installed, all graph features are silently skipped with zero overhead.

How to enable:

# 1. Install GitNexus (requires Node.js)
npm install -g gitnexus

# 2. Refresh (auto-indexes the code graph)
ag-refresh --workspace my-project

# 3. Ask β€” graph enrichment is automatic
ag-ask "Who calls the send method in gateway adapters?"
# Router decides: GRAPH: yes β†’ queries GitNexus β†’ enriched answer
Sandbox β€” Configurable code execution environment
Variable Default Options
SANDBOX_TYPE local local Β· microsandbox
SANDBOX_TIMEOUT_SEC 30 seconds

See Sandbox docs.


Real-World Eval: MiniMax2.7 on OpenClaw (12K files, 348K stars)

Tested against OpenClaw β€” the most popular open-source AI assistant (TypeScript + Swift + Kotlin, 12,133 files) β€” using MiniMax2.7 free API.

Refresh results

$ ag-refresh --workspace /path/to/openclaw
[1/3] Scanning project... 5000 files, 0.14s
[7/8] β–Ά Running 154 modules (concurrency=8)...
      Auto-split: extensions/ β†’ 50+ sub-modules (slack, telegram, whatsapp, ...)
      Auto-split: src/ β†’ 40+ sub-modules (agents, gateway, config, ...)
[8/8] module_registry βœ… 164 lines

Total time: 42m52s | 111 module docs | 1.5MB knowledge base

Ask evaluation matrix (11 tests)

Category Question Result Quality
Basic understanding "What is this project?" Pass 5/5 β€” sponsors, platforms, features, structure
Tech stack "Tech stack and frameworks?" Timeout 3/5 β€” fallback gave language/framework data
Module deep-dive "How does Telegram integration work?" Pass 5/5 β€” file table + architecture diagram + types + constants
Module deep-dive "Discord voice channels?" Pass 5/5 β€” audio pipeline + code samples + design patterns
Module deep-dive "WhatsApp integration?" Pass 5/5 β€” auth flow + plugin architecture + dependencies
Hallucination test "Does this support GraphQL?" 413 0/5 β€” request too large for free API
Architecture "How does Gateway work?" Timeout 2/5 β€” file list but no analysis
Chinese query "ζ”―ζŒε“ͺδΊ›AIζ¨‘εž‹οΌŸ" Timeout 1/5 β€” cross-module, needs faster model
Skills system "What is the skill system?" Timeout 2/5 β€” listed skill files
Testing patterns "Testing frameworks?" Timeout 2/5 β€” listed vitest configs
Platform listing "What messaging platforms?" Crash 0/5 β€” 413 error

Key finding: auto-split unlocks module-level excellence

 βœ… Module-level Q&A (5/5)              ⚠️ Cross-module questions              ❌ Free API limits
 ──────────────────────────             ────────────────────────              ─────────────────
 Telegram: architecture diagram         Gateway: timeout                      413 on large context
 Discord: audio pipeline + code         Testing: timeout                      Rate limiting (429)
 WhatsApp: auth + plugin system         Tech stack: timeout
 Each module has its own knowledge doc  Needs faster model or higher timeout

Scores

Dimension Score Notes
Basic Q&A 9/10 Project overview excellent
Module deep-dive 10/10 Telegram/Discord/WhatsApp β€” architecture diagrams, types, design patterns
Cross-module 3/10 Gateway, Testing, Skills β€” timeout with free API
Overall 6.5/10 Module Q&A: production-ready even on 12K-file projects. Cross-module: needs faster model.

Performance comparison

Metric OpenCMO (374 files) OpenClaw (12K files) Improvement
Refresh time ~10 min 43 min Parallel + auto-split
Module docs 9 111 12x
Knowledge base 540KB 1.5MB 2.8x
Module Q&A quality 7/10 10/10 Auto-split = focused knowledge

What changed: Large modules (extensions/ with 262 groups, src/ with 363 groups) are now auto-split into independent sub-modules. All modules run in parallel (8 concurrency). This reduced OpenClaw refresh from 5+ hours (never finished) to 43 minutes (completed).

Quick config for best results

# .env β€” recommended settings after eval
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_API_KEY=your-key
OPENAI_MODEL=your-model

# Tuning β€” raise timeouts for large repos
AG_ASK_TIMEOUT_SECONDS=120
AG_REFRESH_AGENT_TIMEOUT_SECONDS=180
AG_MODULE_AGENT_TIMEOUT_SECONDS=300
AG_API_CONCURRENCY=5           # Max simultaneous LLM calls (prevents rate-limiting)
AG_MAX_GROUP_CHARS=800000      # Hard char limit per group (prevents context overflow)

Works with any OpenAI-compatible provider: NVIDIA, OpenAI, Ollama, vLLM, LM Studio, Groq, MiniMax, etc.


Earlier Eval: MiniMax2.7 on OpenCMO (374 files, 29K lines)

Tested end-to-end against the OpenCMO codebase (Python + React/TS, 374 files) using MiniMax2.7 via an OpenAI-compatible router.

Ask evaluation matrix (18 tests)

Category Question Result Quality
Basic understanding "What is this project?" Pass 5/5 β€” accurate summary with tech details
Tech stack "What tech stack and frameworks?" Pass 5/5 β€” frontend + backend + libs listed
Module listing "List all main modules" Pass 5/5 β€” table format, accurate
API routing "How does API routing work?" Pass 5/5 β€” routes + endpoints + client code
Precise function "get_model() in llm.py signature" Pass 5/5 β€” 100% accurate file, line, logic
Hallucination test "Does this support GraphQL?" Pass 5/5 β€” correctly said No with 4-point evidence
Chinese query "η€ΎεŒΊη›‘ζŽ§ζ”―ζŒε“ͺ些平台?" Pass 5/5 β€” Chinese answer, platform style table
Database schema "List all database tables" Pass 5/5 β€” 34 tables listed with source file
Approval workflow "How does approval work?" Pass 5/5 β€” full state machine with line numbers
Complex architecture "How does multi-agent work?" (120s) Pass 5/5 β€” 20 agents listed, comm patterns

Scores

Dimension Score Notes
Basic Q&A 9/10 Project, tech stack, modules β€” excellent
Code location 7/10 Precise queries great; same-name files can confuse
Hallucination control 9/10 Won't fabricate; gives negative evidence
Multi-language 9/10 Chinese Q&A excellent
Overall 7/10 Daily code Q&A: production-ready. Complex analysis: tune timeout.

Full evaluation report: artifacts/plan_20260404_opencmo_ask_boundary_eval.md


Documentation

πŸ‡¬πŸ‡§ English docs/en/
πŸ‡¨πŸ‡³ δΈ­ζ–‡ docs/zh/
πŸ‡ͺπŸ‡Έ EspaΓ±ol docs/es/

Contributing

Ideas are contributions too! Open an issue to report bugs, suggest features, or propose architecture.

Contributors


⭐ Lling0000

Major Contributor Β· Creative suggestions Β· Project administrator Β· Project ideation & feedback

Alexander Daza

Sandbox MVP Β· OpenSpec workflows Β· Technical analysis docs Β· PHILOSOPHY

Chen Yi

First CLI prototype Β· 753-line refactor Β· DummyClient extraction Β· Quick-start docs

Subham Sangwan

Dynamic tool & context loading (#4) Β· Multi-agent swarm protocol (#3)

shuofengzhang

Memory context window fix Β· MCP shutdown graceful handling (#28)

goodmorning10

Enhanced ag ask context loading β€” added CONTEXT.md, AGENTS.md, and memory/*.md as context sources (#29)

Abhigyan Patwari

GitNexus β€” code knowledge graph natively integrated into ag ask for symbol search, call graphs, and impact analysis

BBear0115

Skill packaging & KG retrieval enhancements Β· Multi-language README sync (#30)

SunkenCost

ag clean command Β· __main__ entry-point guard (#37)

Aravindh Balaji

Unified instruction surface around AGENTS.md (#41)

Star History

Star History Chart

License

MIT License. See LICENSE for details.


πŸ“š Full Documentation β†’

Built for the AI-native development era

About

πŸͺ The ultimate starter kit for AI IDEs, Claude code,codex, and other agentic coding environments.

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages