rag-for-terraform

⬡

Terraform RAG

AI-powered knowledge base for your Terraform modules.

Index, search, compose, and audit - all from one place.

-

-

-

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

Module Browser - 2700+ modules across 175+ repos

Agentic Compose - tool calls and reasoning in real time

Generated HCL - syntax-highlighted output

Knowledge Browser - conventions and usage patterns

Index Jobs - repository indexing dashboard

Audit Logs - full trail of LLM, MCP, and API calls

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.

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`).

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`.

LLM Configuration

A separate cheap model can be used for module descriptions during indexing

(`DESCRIPTION_LLM_*` variables).

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**.

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