sema-mcp 0.1.0

Semantic codebase indexer and MCP server for Claude Code

Sema

Experimental — sema is under active development. APIs and index formats may change between versions. See the disclaimer.

Stop wasting tokens — on navigating your codebase, and on rewriting code that already exists. Speed up Claude Code and OpenAI Codex on large codebases.

Sema is a semantic code indexer and MCP server. It indexes your entire codebase locally — every function, class, and method — and gives your AI assistant a search API so it never reads files blindly again, plus a reuse guard so it stops reinventing helpers you already have.

Works with Claude Code CLI, Claude Code VS Code, OpenAI Codex CLI, and Codex VS Code. Plus sema's own VS Code extension — a chat panel to work with your codebase using Claude or OpenAI, right in the editor.

Features

• 🔍 Semantic search — search_code() finds code by meaning and returns signatures only (~150 tokens), never whole files.
• ♻️ Reuse guard — check_reuse() tells your assistant whether a function already exists before it writes a new one, so it reuses instead of reinventing. 98% reuse-vs-build accuracy in a 50-example eval on real code.
• 🕸️ Impact analysis — impact_analysis() maps the call graph in both directions, so the AI sees the blast radius before a refactor.
• 📁 Multi-project — one sema init --root <dir> serves every indexed repo under a directory; no re-registration when you switch projects.
• 🔒 Local & offline — embeddings run on your machine (SBERT, ~80MB). No API keys, no internet, no code leaves your laptop.
• 🧩 VS Code extension — a codebase-aware chat panel (Claude Code / Codex / Anthropic / OpenAI) plus search, reuse, and index management, right in the editor. Get it on the Marketplace →

Why sema

Every Claude Code and Codex session starts cold. On a large project, your AI assistant burns 10,000–25,000 tokens just navigating — running find, reading full files, building a mental model from scratch — before it can help with anything.

Sema gives it a search index instead. Instead of reading a dozen files to answer "how does auth work?", the AI runs one search_code() and fetches only the exact function bodies it needs — typically 4–11× fewer tokens. Index once. Your AI searches forever.

That's the reading half of the token bill. Sema goes after the writing half too: before your assistant adds a new helper, check_reuse() searches the index for an existing one and answers reuse / review / safe-to-build — so it extends what's already there instead of shipping a fourth function that does the same thing.

See the benchmarks for measured token savings on real open-source repos.

Quick start

# 1. Install — provides the `sema` command
pip install sema-mcp        # or: uv tool install sema-mcp

# 2. Index your project and register with your AI assistant
cd your-project
sema index .
sema init --claude     # or: sema init --codex

# 3. Reload VS Code, then type /mcp to confirm sema is connected

Requires Python 3.11+. On PyPI the package is sema-mcp (the name sema was taken), but the command and import stay sema. Working on sema itself? Install from source.

Then add a CLAUDE.md (or AGENTS.md for Codex) so your assistant calls sema before reading files — see Claude Code setup or OpenAI Codex setup.

Requires Python 3.11+. No Docker, no external APIs, no GPU — everything runs on your machine.

How it works

sema index . uses tree-sitter to parse every function, class, and method, embeds each one locally with SBERT (all-MiniLM-L6-v2), and stores the vectors plus full source in an embedded ChromaDB. A local MCP server then exposes search tools to Claude/Codex over stdio. search_code() returns signatures only; get_code() returns full bodies on demand.

The same index powers the rest of the toolset: check_reuse() (does this already exist?), impact_analysis() (call graph and blast radius), and multi-project serving — all fully offline.

See Architecture for the full picture.

sema for VS Code

Prefer a UI? The sema VS Code extension is on the VS Code Marketplace — it brings the whole toolset into the editor, plus a codebase-aware chat panel:

• 💬 Chat with your code through four providers — Claude Code and Codex running locally (reuse your existing login, no API key; they read the repo and, in Agent mode, edit it), or the Anthropic and OpenAI APIs with your own key.
• 🧭 Ask / Agent modes, a reasoning-effort selector, streamed thinking and tool activity, and per-session memory — just like the terminal apps, and prompts pass straight through (no wrapper persona).
• 🔎 Semantic index toggle — inject sema's retrieved context (RAG) on demand; the same search_code / check_reuse power the panel.
• 🛠️ Manage panel — index status, one-click re-index / register / watch / doctor, and live token usage + estimated cost for the session.
• ⚡ Search and Reuse from the command palette, with index freshness in the status bar.

Install: search "sema" in the Extensions view, run code --install-extension MasihMoloodian.sema-codebase-chat, or open the Marketplace listing. Prefer to build from source? See the extension guide.

Documentation

Full docs live in docs/:

Installation	Requirements, pip install, and install from source
sema for VS Code	sema's own VS Code extension — chat panel, search, reuse, and index management
Claude Code setup · Codex setup · VS Code workspace	Register sema with your assistant
Working with multiple projects	Serve many repos from one registration
CLI reference	Every sema command
MCP tools	The tools your AI assistant calls
Supported languages	AST-aware vs text-aware indexing
Configuration	Config file, env vars, .gitignore
Managing sema	Update, remove, and when to re-index
Troubleshooting	Fixes for common issues
Benchmarks · FAQ · Roadmap	Background and details
Contributing	Development setup and how to extend sema

Contributing

Contributions are welcome — sema is intentionally small and easy to extend. See Contributing for development setup and how to add a new language.

License

MIT License — free to use, modify, and distribute. See LICENSE.

Copyright (c) 2026 Masih Moloodian

Contact

Masih Moloodian · [e-mail]

Issues and feature requests: github.com/masihmoloodian/sema/issues