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 (from the knowledge graph), 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 structured JSON claims with source evidence (file paths + line ranges). A RegistryAgent then summarizes all modules into a semantic registry. During ag-ask, Router reads the registry to understand what each module is responsible for and routes questions to the right ModuleAgent — when structured facts are available, claims are verified against live source before answering. Powered by OpenAI Agent SDK + LiteLLM. Multi-language: Python, TypeScript/JavaScript, Go, Rust, Java, Kotlin, Swift, C/C++, C#.

GitAgent — A dedicated agent for analyzing git history — understands who changed what and why.

GitNexus Enhancement (optional) — Install GitNexus to auto-unlock semantic search, call graphs, and impact analysis for every ModuleAgent.

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    # structured-facts + legacy-swarm ask
        │   ├── refresh_pipeline.py # evidence-driven refresh orchestration
        │   ├── 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,