Metadata-Version: 2.4
Name: sema-mcp
Version: 0.1.0
Summary: Semantic codebase indexer and MCP server for Claude Code
Project-URL: Homepage, https://github.com/masihmoloodian/sema
Project-URL: Issues, https://github.com/masihmoloodian/sema/issues
Author-email: Masih Moloodian <masihmoloodian@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,claude-code,codebase,developer-tools,mcp,semantic-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: chromadb>=0.5
Requires-Dist: click>=8.0
Requires-Dist: gitpython>=3.1
Requires-Dist: mcp>=1.0
Requires-Dist: pathspec>=0.12
Requires-Dist: pydantic>=2.0
Requires-Dist: rank-bm25>=0.2
Requires-Dist: rich>=13.0
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Sema

<p align="center">
  <img src="https://raw.githubusercontent.com/masihmoloodian/sema/main/logo.png" alt="Sema" width="480" />
</p>

> **Experimental** — sema is under active development. APIs and index formats may change between versions. See the [disclaimer](docs/faq.md#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
<a href="https://github.com/anthropics/claude-code"><img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/claude-ai.svg" alt="Claude" height="16" style="vertical-align:middle;" /> **Claude Code CLI**</a>,
<a href="https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code"><img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/vscode.svg" alt="VS Code" height="16" style="vertical-align:middle;" /> **Claude Code VS Code**</a>,
<a href="https://github.com/openai/codex"><img src="https://cdn.jsdelivr.net/npm/@lobehub/icons-static-svg@latest/icons/codex-color.svg" alt="Codex" height="16" style="vertical-align:middle;" /> **OpenAI Codex CLI**</a>,
and
<a href="https://marketplace.visualstudio.com/items?itemName=openai.chatgpt"><img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/vscode.svg" alt="Codex" height="16" style="vertical-align:middle;" /> **Codex VS Code**</a>.
Plus sema's own <a href="https://marketplace.visualstudio.com/items?itemName=MasihMoloodian.sema-codebase-chat"><img src="https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/vscode.svg" alt="VS Code" height="16" style="vertical-align:middle;" /> **VS Code extension**</a> — 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 →](https://marketplace.visualstudio.com/items?itemName=MasihMoloodian.sema-codebase-chat)

## 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](docs/benchmarks.md) for measured token savings on real open-source repos.

## Quick start

```bash
# 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](docs/installation.md#install-from-source-for-development).

Then add a `CLAUDE.md` (or `AGENTS.md` for Codex) so your assistant calls sema before reading files — see [Claude Code setup](docs/claude-code.md) or [OpenAI Codex setup](docs/codex.md).

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()`](docs/mcp-tools.md#check_reuse--dont-rewrite-what-already-exists) (*does this already exist?*), [`impact_analysis()`](docs/mcp-tools.md#impact_analysis--call-graph) (call graph and blast radius), and [multi-project serving](docs/multi-project.md) — all fully offline.

See [Architecture](docs/architecture.md) for the full picture.

## sema for VS Code

[![VS Marketplace Version](https://img.shields.io/visual-studio-marketplace/v/MasihMoloodian.sema-codebase-chat?label=VS%20Code%20Marketplace&color=1e88e5&logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=MasihMoloodian.sema-codebase-chat)
[![Installs](https://img.shields.io/visual-studio-marketplace/i/MasihMoloodian.sema-codebase-chat?color=1e88e5)](https://marketplace.visualstudio.com/items?itemName=MasihMoloodian.sema-codebase-chat)

Prefer a UI? The **[sema VS Code extension](https://marketplace.visualstudio.com/items?itemName=MasihMoloodian.sema-codebase-chat)** 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](https://marketplace.visualstudio.com/items?itemName=MasihMoloodian.sema-codebase-chat). Prefer to build from source? See the [extension guide](vscode-extension/README.md#build-from-source).

## Documentation

Full docs live in [`docs/`](docs/README.md):

| | |
|---|---|
| [Installation](docs/installation.md) | Requirements, `pip install`, and install from source |
| [sema for VS Code](vscode-extension/README.md) | sema's own VS Code extension — chat panel, search, reuse, and index management |
| [Claude Code setup](docs/claude-code.md) · [Codex setup](docs/codex.md) · [VS Code workspace](docs/vscode-workspace.md) | Register sema with your assistant |
| [Working with multiple projects](docs/multi-project.md) | Serve many repos from one registration |
| [CLI reference](docs/cli-reference.md) | Every `sema` command |
| [MCP tools](docs/mcp-tools.md) | The tools your AI assistant calls |
| [Supported languages](docs/languages.md) | AST-aware vs text-aware indexing |
| [Configuration](docs/configuration.md) | Config file, env vars, `.gitignore` |
| [Managing sema](docs/managing-sema.md) | Update, remove, and when to re-index |
| [Troubleshooting](docs/troubleshooting.md) | Fixes for common issues |
| [Benchmarks](docs/benchmarks.md) · [FAQ](docs/faq.md) · [Roadmap](docs/roadmap.md) | Background and details |
| [Contributing](docs/contributing.md) | Development setup and how to extend sema |

## Contributing

Contributions are welcome — sema is intentionally small and easy to extend. See [Contributing](docs/contributing.md) for development setup and how to add a new language.

## License

MIT License — free to use, modify, and distribute. See [LICENSE](LICENSE).

Copyright (c) 2026 Masih Moloodian

## Contact

**Masih Moloodian** · [masihmoloodian@gmail.com](mailto:masihmoloodian@gmail.com)

Issues and feature requests: [github.com/masihmoloodian/sema/issues](https://github.com/masihmoloodian/sema/issues)
