Locus

Locus gives your AI coding agent a map of your codebase. Whether you write code yourself or work through Cursor, Codex, or Claude Code, Locus connects your agent to the same go-to-definition and find-references intelligence your IDE uses — through MCP (Model Context Protocol), a standard plug-in layer for AI tools. Configure it once; your agent uses six small tools to find symbols, trace callers, read types, and catch errors before you run tests.

Why you might want this

• Find the real definition — Your agent can locate UserService.authenticate even when it is re-exported, overloaded, or buried in a large file — not just wherever the name appears as text.
• See who calls what — Before a refactor, list every reference to a function or class so nothing breaks silently.
• Read types and docs — Ask what a variable or parameter actually is, without guessing from variable names.
• Catch errors early — Surface compiler and linter problems right after an edit, instead of waiting for a full test run.

Who this is for

Locus is for AI-first builders: developers, indie hackers, and PMs who work through an agent and want it to understand code structure, not just search strings.

It fits when your agent already edits files well (Cursor's Edit tool, Claude Code, Codex) and you want to add semantic navigation on top — without turning your setup into a second IDE inside MCP.

It is not for people who want symbolic editing, agent memory, or a full refactoring toolkit inside MCP. For that, look at Serena — a broader option that does more inside the protocol. Locus stays intentionally small: six tools, npx install, complements your host.

Get started in 5 minutes

1. Install a language server (if you do not have one yet) — for TypeScript/JavaScript: npm install -g typescript-language-server typescript. See Installing language servers for Python, Go, and Rust.
2. Run one-time setup in your project folder:

   npx @paladini/locus-mcp init
   npx @paladini/locus-mcp check

3. Add Locus to your agent's MCP config — MCP is how AI hosts call helper tools like Locus; copy a block from Copy-paste configs below and set cwd to your project's absolute path.
4. Reload MCP — restart Cursor, reload Codex, or reopen Claude Code so the new server appears.
5. Try a prompt — ask your agent: "Use Locus to find where UserService is defined and list all references." If it calls the locate and refs tools, you are set.

Requirements: Node.js 22+. Language servers on your PATH for the languages you use.

Copy-paste configs

Your agent host spawns Locus automatically — you never run serve by hand during normal use.

Cursor

Create or edit .cursor/mcp.json in your project (or global Cursor MCP settings):

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Codex

Add to ~/.codex/config.toml (global) or .codex/config.toml (project):

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp", "serve"]
cwd = "/absolute/path/to/your/project"

For a project-scoped config, you can use cwd = "." instead.

Claude Code

Add to Claude Code MCP settings:

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

More detail (local dev, troubleshooting): docs/usage.md

Example prompts to try

Paste these into your agent after Locus is configured:

• "Find where UserService is defined. Use Locus locate, not grep."
• "Before we rename parseConfig, use Locus to list every file that calls it."
• "What type does response.data have in src/api/handler.ts? Use Locus hover."
• "After your edits, run Locus diagnostics on the files you changed and fix any errors."
• "Check Locus status — are the language servers ready?"

What Locus does NOT do

• Edit your code — Your agent's Edit/Write tools still apply changes. Locus only reads structure and diagnostics.
• Replace grep — Grep is still best for log lines, config keys, comments, and plain text search.
• Remember things between sessions — No agent memory store; each session starts fresh.
• Run refactors for you — rename previews impact; your agent applies the actual edits.
• Expose every LSP feature — Six focused tools only, not a full IDE protocol passthrough.
• Compete with large toolkits — If you need symbolic body replacement, memory, and 40+ languages in one MCP stack, consider Serena instead.

Tools at a glance

Tool	What it does
locate	Find a symbol by name or list symbols in a file
refs	All references or implementations at a position
hover	Type information and documentation
diagnostics	File or workspace errors and warnings
status	Language-server readiness and missing binaries
rename	Preview a rename (dry-run; apply via your agent)

Learn more

Guide	Description
Usage guide	Step-by-step setup, workflows, troubleshooting
Getting started	First-time setup — no LSP knowledge required
FAQ	Do I need to be a programmer? What's MCP?
Who is Locus for?	Fit, scope, and when to pick alternatives
Comparison	Locus vs Serena, bridges, and grep
Tools reference	All six MCP tools with examples
Configuration	locus.toml, locus.json, language servers
Website	Lightweight positioning and quick overview

License

MIT