Zed Editor Integration

Ragex provides first-class integration with the Zed editor through three mechanisms:

1. MCP Context Server -- Ragex's ~50 tools are available in Zed's Agent Panel
2. Task Runner -- All Ragex mix tasks are accessible via task: spawn
3. Keybindings -- Common operations bound to keyboard shortcuts

Quick Start

Prerequisites

• Zed editor installed (https://zed.dev/)
• Elixir 1.19+ and Erlang/OTP 27+
• Ragex project compiled (mix deps.get && mix compile)
• Elixir extension installed in Zed (search "Elixir" in Extensions)

1. Open the Project

zed /path/to/ragex

Zed will automatically pick up the .zed/settings.json, .zed/tasks.json, and .zed/keymap.json from the project root.

2. Verify MCP Server

Open the Agent Panel (default: Ctrl+Shift+? or from Command Palette: agent: open agent panel).

Click the settings gear icon (top-right) and check that ragex shows a green status dot. If it shows red, check the troubleshooting section below.

3. Start Using

• Agent Panel: Ask the AI questions about your codebase -- it will use Ragex tools automatically
• Task Runner: Press Ctrl+Shift+P, type task: spawn, and pick any task
• Keybindings: Use the shortcuts listed below for quick access

MCP Integration

How It Works

Zed launches bin/ragex-mcp as a child process and communicates with it over stdin/stdout using the MCP protocol (JSON-RPC 2.0). Ragex exposes:

• ~50 Tools: Code analysis, semantic search, RAG queries, refactoring, security scanning, etc.
• 6 Prompts: Pre-built workflows for architecture analysis, impact analysis, code flow explanation, etc.
• 6 Resources: Read-only access to graph stats, cache status, model config, project index, etc.

Agent Profile: "Ragex RAG"

A dedicated agent profile is configured in .zed/settings.json that enables only Ragex-relevant tools. To use it:

1. Open the Agent Panel
2. Click the profile selector (top area)
3. Choose "Ragex RAG"

This disables network-fetching tools and enables all Ragex MCP tools for focused codebase analysis.

Example Prompts

In the Agent Panel, try:

• "Using ragex, analyze the architecture of the lib/ directory"
• "Find all dead code in this project using ragex"
• "What functions call Ragex.Graph.Store.add_node?"
• "Search for code similar to 'validate user authentication'"
• "Run a security scan on lib/ragex/mcp/"
• "Show me the coupling report for this project"

System-Wide Availability

The global Zed config (~/.config/zed/settings.json) includes Ragex as a system-wide MCP server pointing to the absolute path of bin/ragex-mcp. This means Ragex tools are available in the Agent Panel even when working on other projects. Pass --project /path/to/code to auto-analyze a specific codebase:

"context_servers": {
  "ragex": {
    "command": {
      "path": "/home/am/Proyectos/Oeditus/ragex/bin/ragex-mcp",
      "args": ["--project", "/path/to/other/project"],
      "env": {}
    }
  }
}

Task Runner

Available Tasks

All tasks are defined in .zed/tasks.json. Access them via Ctrl+Shift+P > task: spawn.

Testing

Code Quality

Ragex Analysis

Ragex Cache

Ragex ML Models

Ragex Interactive

Build

Keybindings

Defined in .zed/keymap.json. These are project-scoped.

Editor Context (requires open file)

Workspace Context (global)

Configuration Files

Launcher Script

bin/ragex-mcp is the entry point for the MCP server:

# Basic startup (inside project)
bin/ragex-mcp

# Auto-analyze a specific project
bin/ragex-mcp --project /path/to/code

# Override log level
bin/ragex-mcp --log-level debug

# Environment variable alternatives
RAGEX_PROJECT=/path/to/code bin/ragex-mcp
RAGEX_LOG_LEVEL=debug bin/ragex-mcp

The script:

• Sets MIX_ENV=prod for performance
• Enables stdio server (RAGEX_STDIO=1)
• Compiles silently (output to stderr)
• Runs mix run --no-halt for persistent server

Troubleshooting

MCP Server Shows Red Dot

1. Check Zed logs: Ctrl+Shift+P > zed: open logs
2. Look for lines mentioning "ragex"
3. Common causes:
   • bin/ragex-mcp not executable: chmod +x bin/ragex-mcp
   • Dependencies not compiled: run mix deps.get && mix compile first
   • Wrong path in global config: verify the absolute path in ~/.config/zed/settings.json

MCP Server Starts But No Tools Visible

• Switch to the "Ragex RAG" agent profile
• Mention "ragex" by name in your prompt to help the model find the tools
• Verify the server is green in Agent Panel settings

Tasks Not Showing Up

• Make sure you opened the project root (where .zed/ lives) in Zed
• Try Ctrl+Shift+P > zed: open project tasks to check if Zed found the tasks file
• Zed requires the project to be opened as a workspace (not individual files)

Keybindings Not Working

• Project keybindings only apply when the Ragex workspace is active
• Check for conflicts: Ctrl+Shift+P > zed: open keymap
• Some bindings require Editor context (an open file with focus)

Slow Startup

First launch compiles the project and downloads ML models (~400MB). Subsequent starts are fast. To pre-warm:

mix deps.get && mix compile && mix ragex.models.download

Log Location

Ragex logs to ragex.log in the project root (configured in config/config.exs). Tail it for debugging:

tail -f ragex.log