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.xml to 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.xml to 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; --incremental re-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 / PostToolUse hooks 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.json so 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:

| Client | Config file | |--------|-------------| | Claude Code | .claude/settings.json (project) or ~/.claude/settings.json (global) | | Cursor | ~/.cursor/mcp.json | | Claude Desktop | claude_desktop_config.json |

{
  "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/goatlas with the actual binary path (e.g. ~/go/bin/goatlas). Run which goatlas to 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

GoAtl

Goatlas

Install / Use

README