Ragex Cheatsheet

Installation & Setup

Add :ragex to your mix.exs dependencies:

def deps do
  [
    {:ragex, "~> 0.29.0"},
    # Optional local ML vector search acceleration
    {:bumblebee, "~> 0.5", optional: true},
    {:exla, "~> 0.9", optional: true}
  ]
end

Fetch dependencies and compile:

mix deps.get
mix compile

Essential Mix Tasks

# Setup & Initial Configuration Wizard
mix ragex.configure

# Analyze current project codebase
mix ragex.analyze

# Start interactive AI Chat loop in terminal
mix ragex.chat

# Start interactive CLI refactoring wizard
mix ragex.refactor

# Run automated AI codebase audit report
mix ragex.audit --format markdown

# Launch real-time TUI dashboard monitor
mix ragex.dashboard

# Run CI diff-based analysis on pull requests
mix ragex.ci --base main

# Migrate embedding models & recalculate vectors
mix ragex.embeddings.migrate --model sentence-transformers/all-MiniLM-L6-v2

# Cache maintenance
mix ragex.cache.stats
mix ragex.cache.refresh
mix ragex.cache.clear --all

# Shell completions & man pages installation
mix ragex.completions
mix ragex.install_man

Configuration (config/config.exs or .ragex.exs)

import Config

config :ragex,
  # Directory auto-indexing on startup
  auto_analyze_dirs: ["lib", "apps"],
  
  # ML Vector Embedding configuration
  embedding_model: "sentence-transformers/all-MiniLM-L6-v2",
  embedding_batch_size: 32,
  
  # Persistent Database backend (:ets or :per_project dllb Rust server)
  store_backend: :dllb,
  dllb_mode: :per_project,
  
  # AI Provider settings (:deepseek_r1, :openai, :anthropic, :ollama)
  ai: [
    provider: :deepseek_r1,
    model: "deepseek-reasoner",
    api_key: System.get_env("DEEPSEEK_API_KEY"),
    max_tokens: 4096,
    temperature: 0.2
  ],
  
  # Safety & Editing Backups
  backup_dir: ".ragex/backups",
  max_backups: 50,
  auto_format: true

Graph Entity Queries (Ragex.Graph.Store)

# Initialize or fetch default store
{:ok, store} = Ragex.Graph.Store.start_link(name: :my_store)

# Analyze a single file
Ragex.Analyzers.Elixir.analyze_file("lib/my_app/user.ex", store)

# List all indexed modules
modules = Ragex.Graph.Store.list_nodes(store, type: :module)

# Find function calls & relationship edges
callers = Ragex.Graph.Store.get_callers(store, "User.create/1")
callees = Ragex.Graph.Store.get_callees(store, "User.create/1")

Graph Algorithms (Ragex.Graph.Algorithms)

# Compute PageRank for codebase entity importance
{:ok, ranks} = Ragex.Graph.Algorithms.page_rank(store, damping_factor: 0.85)

# Find execution call paths between two functions
{:ok, paths} = Ragex.Graph.Algorithms.find_paths(
  store,
  "MyAppWeb.UserController.create/2",
  "MyApp.Repo.insert/1",
  max_depth: 6,
  max_paths: 50
)

# Betweenness Centrality (detect bottleneck modules)
{:ok, centrality} = Ragex.Graph.Algorithms.betweenness_centrality(store)

# Architectural Community Detection (Louvain algorithm)
{:ok, communities} = Ragex.Graph.Algorithms.detect_communities(store, algorithm: :louvain)

# Export graph visualizer file (DOT format)
{:ok, dot_string} = Ragex.Graph.Algorithms.export_graph(store, format: :dot)
File.write!("graph.dot", dot_string)

Neural Vector Search (Ragex.VectorStore)

# Natural language semantic code query (<50ms execution)
{:ok, results} = Ragex.VectorStore.search(
  store,
  "function that validates password hash and strength",
  limit: 10,
  min_score: 0.65
)

# Inspect vector score and node metadata
Enum.each(results, fn %{node: node, score: score} ->
  IO.puts("[#{Float.round(score, 3)}] #{node.name} (#{node.file}:#{node.line})")
end)

Hybrid Retrieval & RRF Fusion (Ragex.Retrieval.Hybrid)

# Reciprocal Rank Fusion (combining vector search + graph centrality)
{:ok, hybrid_results} = Ragex.Retrieval.Hybrid.search(
  store,
  "handle Stripe webhook event idempotency",
  strategy: :rrf,        # :rrf, :semantic_first, or :graph_first
  rrf_k: 60,
  limit: 15
)

Safe File Operations (Ragex.Editor)

# Safe atomic file edit with automatic syntax checking & backup creation
{:ok, edit_result} = Ragex.Editor.Core.edit_file(
  "lib/my_app/user.ex",
  [
    %{
      type: :replace,
      start_line: 14,
      end_line: 18,
      replacement: """
      def verify_password(user, password) do
        Bcrypt.verify_pass(password, user.password_hash)
      end
      """
    }
  ],
  format: true  # Auto-invoke mix format
)

# Undo / Rollback to previous version
{:ok, restored_file} = Ragex.Editor.Undo.rollback("lib/my_app/user.ex")

Multi-File Transaction Editing (Ragex.Editor.Transaction)

# Atomic multi-file edit transaction (All-or-Nothing guarantee)
edits_by_file = %{
  "lib/my_app/auth.ex" => [%{type: :replace, start_line: 5, end_line: 5, replacement: "def check_token(t) do"}],
  "lib/my_app_web/plug.ex" => [%{type: :replace, start_line: 12, end_line: 12, replacement: "Auth.check_token(token)"}]
}

case Ragex.Editor.Transaction.apply_transaction(edits_by_file) do
  {:ok, results} -> IO.puts("Multi-file edits applied cleanly!")
  {:error, reason, failed_file} -> IO.puts("Transaction aborted & rolled back on #{failed_file}: #{inspect(reason)}")
end

AST Semantic Refactorings (Ragex.Editor.Refactor)

# Project-wide function rename across all caller sites & arities
{:ok, report} = Ragex.Editor.Refactor.rename_function(
  store,
  "MyApp.Auth",
  "valid_credentials?",  # old name
  "authenticated?",      # new name
  arity: 2
)

# Project-wide module rename (updates definitions, aliases, and imports)
{:ok, report} = Ragex.Editor.Refactor.rename_module(
  store,
  "MyApp.OldAccount",
  "MyApp.UserAccount"
)

# Advanced Refactorings: Change Parameter Signature
{:ok, report} = Ragex.Editor.Advanced.change_signature(
  store,
  "MyApp.User.create/2",
  add_params: [%{name: "opts", default: "[]", index: 2}]
)

Quality & Complexity Audits (Ragex.Analysis)

# Dead code detection with confidence scoring
{:ok, dead_functions} = Ragex.Analysis.DeadCode.analyze(store, min_confidence: 0.7)

# Coupling & Instability analysis (Ca, Ce, Instability score)
{:ok, coupling_report} = Ragex.Analysis.DependencyGraph.analyze_coupling(store)
IO.puts("Instability (I): #{coupling_report["MyApp.User"].instability}")

# Duplication Analysis (Type I - Type IV clones)
{:ok, duplicates} = Ragex.Analysis.Duplication.analyze_directory("lib/", min_similarity: 0.85)

# Cyclomatic & Cognitive Complexity metrics
{:ok, quality} = Ragex.Analysis.Quality.analyze_file("lib/my_app/complex_service.ex")
IO.puts("Cognitive Complexity: #{quality.cognitive_complexity}")

Business Logic & Security Scans

# Run 20 Business Logic Analyzers (callback hell, missing telemetry, N+1 queries)
{:ok, logic_issues} = Ragex.Analysis.BusinessLogic.analyze_project(".")

# Security Vulnerability & Secret Audit
{:ok, sec_report} = Ragex.Analysis.Security.audit_codebase(".")
{:ok, secrets} = Ragex.Analysis.Security.check_secrets(".")

Client Launcher Script (bin/ragex-mcp)

Run directly from stdin/stdout MCP client harness:

# Stdio mode (default launcher)
bin/ragex-mcp --project /path/to/my_project

# Socket daemon bridge mode
bin/ragex-mcp --socket /tmp/ragex.sock

IDE Configuration Manifests

Claude Desktop (~/.config/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "ragex": {
      "command": "/path/to/ragex/bin/ragex-mcp",
      "args": ["--project", "/path/to/your/elixir_app"]
    }
  }
}

Zed Editor (~/.config/zed/settings.json)

{
  "context_servers": {
    "ragex": {
      "command": {
        "path": "/path/to/ragex/bin/ragex-mcp",
        "args": ["--project", "/path/to/your/elixir_app"]
      }
    }
  }
}

Top MCP Tool Signatures for Prompt Engineering

MCP Resource URIs (ragex://)

• ragex://stats/graph — Node/edge counts, PageRank distribution, degree statistics.
• ragex://cache/status — Vector cache integrity, file tracking metadata, stale entities.
• ragex://models/config — Local embedding model details and RAM footprint.
• ragex://index/project — Tracked files list and language percentage breakdown.
• ragex://analysis/summary — High-level code quality, community modularity clusters.