GoAtlas
GoAtlas is an AI-powered code intelligence platform that helps LLMs and developers deeply understand large codebases — combining multi-language AST parsing, a Neo4j knowledge graph, pgvector semantic search, and a pluggable LLM backend, all exposed via the Model Context Protocol (MCP).
What Makes It Different
- Multi-Language — Go, TypeScript/JSX, Python, and Java parsed via AST (tree-sitter); symbols, endpoints, imports extracted per language
- Zero-Config Auto-Discovery — Reads
go.mod,package.json,requirements.txt,pom.xmlto automatically activate connection detection patterns for gRPC, Kafka, HTTP clients, and more - Cross-Service Connection Detection — Detects inter-service connections (gRPC, Kafka, HTTP) across Go, TS, Python, and Java with no config required
- Knowledge Graph — Neo4j graph of packages, files, functions, types with import/call/implementation edges
- Hybrid BM25 + Semantic Search — Reciprocal Rank Fusion merges keyword and vector results; semantic search via Gemini or Ollama embeddings
- Process & Community Detection — BFS from entry points traces execution flows; Louvain clustering groups code communities
- Pluggable LLM — Supports Gemini (
gemini-2.0-flash), Ollama (any local model), and any OpenAI-compatible API (vLLM, LiteLLM, etc.) for both embeddings and agentic Q&A - MCP Server — 22 tools, 5 resources, 3 prompts via stdio for Cursor, Claude Desktop, and any MCP client
- Claude Code Hooks — SessionStart/PreToolUse/PostToolUse integration for session context injection, semantic enrichment, and incremental re-indexing
- AI-Generated Docs — SKILL.md per community cluster and full Markdown wiki from the knowledge graph
Architecture
graph TB
subgraph CLI["GoAtlas CLI"]
direction LR
IDX["index"]
EMB["embed"]
GR["build-graph"]
DET["detect"]
ASK["ask"]
CHT["chat"]
SRV["serve"]
SKL["skills"]
WK["wiki"]
end
subgraph Core["Core Engine"]
direction TB
PARSER["AST Parsers\nGo · TS/JSX · Python · Java"]
INDEXER["Code Indexer\nsymbols · endpoints · connections"]
CATALOG["Auto-Discovery\ngo.mod · package.json · pom.xml"]
PROCDET["Process Detector\nBFS from entry points"]
COMMDET["Community Detector\nLouvain algorithm"]
AGENT["LLM Agent\nGemini or Ollama"]
DOCGEN["Doc Generator\nskills · wiki"]
MCP["MCP Server\ntools · resources · prompts"]
end
subgraph Data["Data Layer"]
PG["PostgreSQL + pgvector\nsymbols · endpoints · embeddings"]
NEO["Neo4j\nknowledge graph"]
LLM["LLM Backend\nGemini API or Ollama"]
QD["Qdrant (optional)\nvector backend"]
end
subgraph Clients["AI Assistants"]
CURSOR["Cursor"]
CLAUDE["Claude Desktop"]
HOOKS["Claude Code Hooks"]
ANY["Any MCP Client"]
end
IDX --> PARSER & CATALOG --> INDEXER --> PG
EMB --> LLM --> PG
GR --> NEO
DET --> PROCDET & COMMDET --> PG
ASK & CHT --> AGENT --> MCP
SKL & WK --> DOCGEN --> LLM
SRV --> MCP
MCP --> PG & NEO & LLM
CURSOR & CLAUDE & HOOKS & ANY --> MCP
Features
Code Intelligence
- Multi-Language Parsing — Go, TypeScript/JSX, Python, Java via AST (tree-sitter for Python/Java)
- Symbol Extraction — Functions, types, methods, interfaces, constants, variables per file
- API Endpoint Detection — HTTP routes from go-zero, gin, echo, chi, net/http, Spring MVC, and more
- Cross-Service Connection Detection — Auto-detects gRPC, Kafka, HTTP clients across all 4 languages
- Zero-Config Auto-Discovery — Reads
go.mod,package.json,requirements.txt,pom.xmlto activate connection patterns automatically - Call Graph — Function-level call edges with 7-tier confidence scoring
- Interface Resolution — Detects struct-implements-interface relationships
Search & Discovery
- Keyword Search — PostgreSQL full-text search on symbol names and signatures
- Semantic Search — Vector similarity via Gemini or Ollama embeddings (pgvector or Qdrant backend)
- Hybrid Search (RRF) — Reciprocal Rank Fusion merging BM25 + vector scores for best results
- Symbol Lookup — Find symbols by name with kind filter
Process & Community Detection
- Process Detection — Forward BFS from HTTP handlers, Kafka consumers, and
main()entry points - Community Detection — Louvain modularity clustering groups tightly-connected code into named communities
- Confidence Scoring — 7-tier scores on call-graph edges and interface implementations
Knowledge Graph (Neo4j)
- Package → File → Symbol relationships
- Import edges between packages
- IMPLEMENTS edges between types and interfaces
- Service dependency mapping
AI Agent
- Pluggable LLM — Gemini (
gemini-2.0-flash) or Ollama (any local model) - Agentic Loop — Up to 20 tool-calling iterations per question
- Multi-Turn Chat — Full conversation history support
- Dynamic System Prompt — Includes repo summary, services, and available tools
Auto-Generated Documentation
- SKILL.md Generation — AI-generated skill files per community cluster for persistent Claude Code context
- Wiki Generation — Full Markdown wiki (services, communities, architecture) from the knowledge graph
Incremental Indexing
- Git-Aware — Tracks last indexed commit;
--incrementalre-indexes only changed files - Staleness Detection — Check if index is behind
git HEAD - Claude Code Hooks — PostToolUse hook auto-triggers incremental re-index on file writes
Quick Start
Choose the setup path that fits you:
🐳 Option A — Docker (all-in-one)
Everything runs in containers — no manual DB setup needed.
1. Clone the repo
git clone https://github.com/xdotech/goatlas
cd goatlas
2. Start all services
GEMINI_API_KEY=your_key make docker-up
Builds GoAtlas and starts PostgreSQL, Neo4j, and Qdrant. Migrations run automatically on startup.
To use Ollama instead of Gemini:
LLM_PROVIDER=ollama EMBED_PROVIDER=ollama make docker-up
To use an OpenAI-compatible API (vLLM, LiteLLM, etc.):
OPENAI_BASE_URL=http://10.1.1.246:8001/v1 OPENAI_MODEL=qwen3.5-35b OPENAI_API_KEY=ignored LLM_PROVIDER=openai make docker-up
3. Index your repo
docker compose exec goatlas ./goatlas index /path/to/your/repo
4. Ask questions
docker compose exec goatlas ./goatlas ask "How does the payment service connect to Kafka?"
💻 Option B — Direct Install
Install the binary and connect to your own PostgreSQL and Neo4j.
1. Install
go install github.com/xdotech/goatlas@latest
2. Start PostgreSQL and Neo4j
You can use the provided compose file for just the databases:
docker compose up -d postgres neo4j
Or bring your own — just make sure DATABASE_DSN and NEO4J_URL point to them.
3. Run migrations
export DATABASE_DSN=postgres://goatlas:goatlas@localhost:5432/goatlas
goatlas migrate
4. Index your repo
goatlas index /path/to/your/repo
5. Ask questions
GEMINI_API_KEY=your_key goatlas ask "How does the payment service connect to Kafka?"
goatlas chat # interactive multi-turn session
Claude Code Integration
The fastest way to get GoAtlas working inside Claude Code — both as hooks and as an MCP server.
Option A — Claude Code Hooks (recommended)
Hooks automatically enrich every Grep/Glob search with semantic context and re-index files after edits.
# Run once inside your repo
goatlas hooks install .
The command will:
- Install
SessionStart/PreToolUse/PostToolUsehooks in.claude/settings.json - Prompt you for
DATABASE_DSN,GEMINI_API_KEY, and Neo4j credentials if not already configured - Save those values to
~/.claude/settings.jsonso they work in every project
To update credentials later, edit the
"env"section in~/.claude/settings.json.
Option B — MCP Server
Connect GoAtlas as a full MCP server to get all 22 tools available in Claude Code, Cursor, or Claude Desktop.
Add the following config to the appropriate file for your client:
{
"mcpServers": {
"goatlas": {
"command": "/path/to/goatlas",
"args": ["serve"],
"env": {
"DATABASE_DSN": "postgres://goatlas:goatlas@localhost:5432/goatlas",
"NEO4J_URL": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"NEO4J_PASS": "goatlas_neo4j",
"GEMINI_API_KEY": "your_gemini_api_key"
}
}
}
}
Replace
/path/to/goatlaswith the actual binary path (e.g.~/go/bin/goatlas). Runwhich goatlasto find it.
Tip: You can use both hooks and MCP together — hooks handle background enrichment and re-indexing, while MCP gives you direct tool access from the chat interface.
LLM Providers
GoAtlas supports Gemini (default), Ollama (local), and any OpenAI-compatible API (vLLM, LiteLLM, text-generation-inference, LocalAI, etc.) for both chat and embeddings, configured independently.
Ollama example — run entirely locally:
LLM_PROVIDER=ollama
EMBED_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2
OLLAMA_EMBED_MODEL=nomic-embed-text
OpenAI-compatible example — connect to vLLM, LiteLLM, or any OpenAI-compatible server:
LLM_PROVIDER=openai
OPENAI_BASE_URL=http://10.1.1.246:8001/v1
OPENAI_API_KEY=ignored
OPENAI_MODEL=qwen3.5-35b
Note: Switching embedding models requires re-running
go run . embed --forcesince vector dimensions differ (Geminitext-embedding-004= 768 dims,nomic-embed-text= 768 dims,mxbai-embed-large= 1024 dims).
Multi-Language Support
GoAtlas auto-discovers connection patterns by reading your dependency files — no manual config needed.
Custom patterns can be added via patterns.yaml in the repo root — they merge additively with catalog defaults.
MCP Tools
GoAtlas exposes 22 MCP tools via stdio transport:
Resources — goatlas://repositories, goatlas://endpoints, goatlas://communities, goatlas://processes, goatlas://schema
Prompts — detect_impact, generate_map, explain_community
CLI Reference
goatlas index <path> # index a repository
goatlas index --force <path> # force re-index all files
goatlas index --incremental <path> # only changed files since last commit
goatlas embed # generate vector embeddings
goatlas embed --force # re-embed everything
goatlas build-graph # populate Neo4j knowledge graph
goatlas detect # process + community detection
goatlas ask "<question>" # single-shot AI Q&A
goatlas chat # interactive multi-turn session
goatlas serve # start MCP server (stdio)
goatlas skills generate <path> # generate SKILL.md per community
goatlas wiki <output-dir> # generate Markdown wiki
goatlas check-coverage spec.md # spec implementation coverage
goatlas hooks install <path> # install Claude Code hooks
goatlas migrate # run database migrations
Environment Variables
Development
make build # compile binary
make test # run tests
make lint # run linter
make docker-up # build & start all services (migrations run automatically)
make docker-down # stop all services
make migrate # run migrations manually (local dev without Docker)
License
MIT
