ag-refresh builds a knowledge base. ag-ask answers questions. Any LLM, any IDE.
Language: English | δΈζ | EspaΓ±ol
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.
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/ 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.
| 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.
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/testsag init my-project
# Already initialized? Use --force to overwrite:
ag init my-project --forceCreates AGENTS.md (authoritative behavior rules), IDE bootstrap files (.cursorrules, CLAUDE.md, .windsurfrules, .clinerules, .github/copilot-instructions.md), and .antigravity/ dynamic context files.
ag-refresh --workspace my-project9-step pipeline:
- Scan codebase (languages, frameworks, structure)
- Multi-agent pipeline generates
conventions.md - Generate
structure.mdβ language-agnostic file tree with line counts - Build knowledge graph (
knowledge_graph.json+ mermaid) - Write document/data/media indexes
- 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. - RefreshGitAgent analyzes git history, generates
_git_insights.md - Map Agent reads all agent docs β generates
map.md(module routing index with descriptions and key topics) - GitNexus indexing (optional) β runs
gitnexus analyzeto build a Tree-sitter code graph (16 languages, call chains, dependencies). Auto-skipped if GitNexus is not installed.
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 β readsagents/*.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.
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.
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/projectTools 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.mdfiles (one per group) β no merging or compression. Duringag-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_CONCURRENCYlimits total simultaneous LLM calls across all modules, preventing rate-limiting. - Language-agnostic module detection: Pure directory structure β no
__init__.pyor 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 answerSandbox β Configurable code execution environment
| Variable | Default | Options |
|---|---|---|
SANDBOX_TYPE |
local |
local Β· microsandbox |
SANDBOX_TIMEOUT_SEC |
30 |
seconds |
See Sandbox docs.
Tested against OpenClaw β the most popular open-source AI assistant (TypeScript + Swift + Kotlin, 12,133 files) β using MiniMax2.7 free API.
$ 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
| 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 |
β
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
| 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. |
| 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).
# .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.
| 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 |
| 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
| π¬π§ English | docs/en/ |
| π¨π³ δΈζ | docs/zh/ |
| πͺπΈ EspaΓ±ol | docs/es/ |
Ideas are contributions too! Open an issue to report bugs, suggest features, or propose architecture.
![]() β 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)
|
MIT License. See LICENSE for details.
Built for the AI-native development era










