goatlas

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:

1. Install SessionStart / PreToolUse / PostToolUse hooks in .claude/settings.json
2. Prompt you for DATABASE_DSN, GEMINI_API_KEY, and Neo4j credentials if not already configured
3. 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:

{
  "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

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 --force since vector dimensions differ (Gemini text-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