Terraform RAG

Try the live demo

Web UI - browse 2700+ modules across 175+ repos (AWS / Azure / GCP):

https://terraform-rag.io

Login: demo@terraform-rag.io / demo (read-only)

MCP - connect your IDE to the knowledge base:

{
  "mcpServers": {
    "terraform-rag": {
      "type": "http",
      "url": "https://terraform-rag.io/mcp",
      "headers": {
        "Authorization": "Bearer trag_6c495d7a027369cb5d324d877626c272"
      }
    }
  }
}

9 tools available: query_modules, pick_modules, list_modules, get_module_details, get_dependencies, get_module_usage, find_similar_usages, fetch_example_code, get_stats (list_modules also takes semantic_query for natural-language search).

What it does

Point it at your Terraform module repositories. It clones them, parses every HCL file, generates embeddings, and builds a searchable knowledge base in PostgreSQL + pgvector. Then it learns how those modules are actually used across your consumer repos - naming patterns, variable conventions, tagging strategies, deployment layouts - and distils that into authoritative guidance.

An agentic pipeline (Claude, Bedrock, or any OpenAI-compatible model) explores the knowledge base across multiple tool-use turns to assemble grounded, reviewable answers - assistive retrieval with a human in the loop, not an autonomous code generator. Query from the web UI, the REST API, or directly from your IDE via MCP.

See it in action

Features

Agentic Query Pipeline - more than a single RAG lookup. The LLM browses modules, checks details, reads conventions, and fetches example code across multiple tool-use turns before composing an answer for you to review. Four query modes: compose, search, optimize, and audit.

Knowledge Layer - indexes consumer repos to learn real-world usage patterns. Distils conventions across six dimensions (naming, variables, tagging, layout, versions, deployment) and treats them as authoritative guidance in all prompts.

MCP Server - Streamable HTTP endpoint works with Claude Code, Cursor, Windsurf, and any MCP-compatible client. Query your module knowledge base directly from your IDE.

Dependency Graph - PostgreSQL recursive CTEs map the full dependency tree between modules. Find what depends on what, trace impact, and visualize relationships with a D3 force-directed graph.

Version Tracking - automatic git tag discovery with per-module version history. Code-hash caching avoids redundant LLM/embedding calls on re-index.

Flexible LLM Backend - Anthropic (direct or Bedrock), OpenRouter, Ollama, or any OpenAI-compatible endpoint. Swap models without changing code.

CI/CD Integration - GitHub Actions workflow and webhook endpoints for automatic re-indexing when .tf files change.

Authentication - disabled (default), local email/password with JWT, or ALB-terminated SSO via AWS Identity Center / OIDC.

MCP Server

Connect any MCP-compatible client to http://localhost:8000/mcp/.

Claude Code (.mcp.json):

{
  "mcpServers": {
    "terraform-rag": {
      "type": "http",
      "url": "http://localhost:8000/mcp/"
    }
  }
}

Available tools: query_modules, pick_modules, list_modules, get_module_details, get_dependencies, get_module_usage, find_similar_usages, fetch_example_code, get_stats.

Architecture

  Browser         AI Agent / IDE
     |               |
+---------+      +--------+      +----------------+
| Frontend|----->|  API   |----->| PostgreSQL 16  |
| (Vite)  |      | FastAPI|      | + pgvector     |
+---------+      +---+----+      +----------------+
                     |
                +----+----+
                | Worker  |      +-------+
                | (Celery)|----->| Redis |
                +---------+      +-------+

For the full technical deep-dive - stack details, directory structure, API endpoints, agent internals, knowledge layer pipeline, known limitations, and deployment notes - see docs/ARCHITECTURE.md.

Quick Start

# 1. Clone and configure
git clone https://github.com/krzysztofgawrys/rag-for-terraform.git
cd rag-for-terraform
cp .env.example .env
# Edit .env - set POSTGRES_PASSWORD, JWT_SECRET, and your LLM API key

# 2. Start everything
docker compose up -d

# 3. Index your first repo
curl -X POST http://localhost:8000/index/ \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "git@github.com:org/tf-modules.git", "branch": "main"}'

For private repos, place your SSH deploy key at ./worker_deploy_key (or set SSH_KEY_PATH in .env).

LLM Configuration

A separate cheap model can be used for module descriptions during indexing (DESCRIPTION_LLM_* variables).

License

Business Source License 1.1 - see LICENSE for details.

• Non-production use (evaluation, testing, development) is permitted
• Production use requires a commercial license from the author
• On 2029-05-25 the license converts to AGPL-3.0