Sema
Sema is an agentic code engine. It indexes your repository once, locally, then
puts that index in front of whichever model you point it at — so every provider
starts out already knowing your code, and you can switch provider and model
mid-conversation without losing the thread.
It runs in three places, and they share one index and one session:
| Surface | What it is |
|---|
| VS Code extension | A Cursor-style chat panel with eleven engines, agent permissions, and an opt-in redaction toggle |
sema chat | The same agent as a terminal app — modes, tools, slash commands, resumable sessions |
| MCP server | Register sema with Claude Code, Codex, opencode, Grok Build, or Cursor and they get semantic search in their own CLI — no extension needed |
Use one, or all three.
Experimental · macOS and Linux · Requires Python 3.11+ · Nothing leaves your machine. Disclaimer
Quick start
1. Install the CLI (bootstraps uv + Python if needed):
curl -fsSL https://raw.githubusercontent.com/get-sema/sema/main/install.sh | sh
2. Index your project and register your AI CLIs:
cd your-project
sema index . # build the local semantic index
sema setup # register with every detected client: Claude Code, Codex, opencode, Grok Build, Cursor
3. Pick a surface:
sema chat # the terminal agent (needs the chat extra — see below)
…or install the VS Code extension
(search "sema" in the Extensions view). Its Manage panel does everything
the CLI does — index, register, update — in a click.
Want just the extension, or just the index? Both work standalone.
Installation guide →
📦 sema-mcp on PyPI · 🧩 Extension on the VS Code Marketplace
Eleven providers, no lock-in
Five local CLIs reuse the subscription you already pay for — no API key, no
re-login. Six API providers need one key each.
| Provider | Kind | Needs |
|---|
| Claude Code | Local CLI | your existing claude login |
| Codex | Local CLI | your existing codex login |
| opencode | Local CLI | your existing opencode login |
| Grok Build | Local CLI | your existing grok login |
| Cursor Agent | Local CLI | your existing cursor-agent login |
| Claude (Anthropic) | API | ANTHROPIC_API_KEY |
| OpenAI | API | OPENAI_API_KEY |
| DeepSeek | API | DEEPSEEK_API_KEY |
| OpenRouter | API | OPENROUTER_API_KEY |
| Together AI | API | TOGETHER_API_KEY |
| AvalAI | API gateway | AVALAI_API_KEY |
AvalAI (api.avalai.ir) is an OpenAI-compatible gateway to Claude, GPT,
Gemini, Grok, and open models that stays reachable from networks where the vendor
APIs are blocked — keep it configured as the escape hatch for an internet outage.
It covers the API path only: the local CLIs still talk to their own vendors.
Provider, model, and reasoning effort are all switchable inside a running
conversation — the history, the index, and your redaction and guard settings
carry over. Start on the subscription you pay for, finish on a cheap (or free)
model.
Why
Cursor is great — it's also a subscription and a walled garden. Claude Code and
Codex are great too, but they lock you to one model per session, and they start
every session cold: burning tokens just navigating before they answer
anything.
Sema indexes your code once, locally. Your assistant searches that index instead
— typically 4–11× fewer tokens per question. And check_reuse() tells it
whether a helper already exists before it writes a fourth one.
| |
|---|
| 4–11× | fewer tokens per question |
| 98% | reuse-vs-build accuracy (50-example eval) |
| ~150 | tokens per search — signatures, not whole files |
| 0 | code that leaves your machine |
The index is built from tree-sitter ASTs for TypeScript, JavaScript, Python and
Go (text-aware for everything else), embedded locally with all-MiniLM-L6-v2,
and searched as a hybrid of semantic similarity and BM25. No API keys, no
network. Supported languages →
Why sema exists, in full → · Benchmarks →
sema chat — the terminal agent
A full coding agent in your terminal, on the same index:
uv sync --extra chat # or: pip install 'sema-mcp[chat]'
cd your-project
sema chat
sema chat --print "where is auth handled?" # one-shot, for scripts
sema chat --resume <session_id> # pick a conversation back up
sema chat --mode plan # read-only + a plan artifact
- Three modes —
ask (no tools, just conversation), plan (read-only
tools), agent (reads, writes, and runs commands). Shift+Tab cycles them.
- 34 slash commands —
/provider, /model, /effort, /search, /reuse,
/impact, /index, /devops, /cost, /sessions, and more. Press /.
- Per-tool permissions — read-only tools run; anything that mutates asks
first.
--yes auto-approves for unattended runs.
- Shared sessions — a conversation started in VS Code resumes in the
terminal, and back again.
Terminal app guide →
What the AI gets
Eight code-intelligence tools, over MCP or in-chat:
| Tool | Purpose |
|---|
search_code | Hybrid semantic + BM25 search over the index |
check_reuse | Does this helper already exist? reuse / review / safe-to-build |
get_code | Full source of a function, class, or method by name |
repo_map | Compressed architecture map — files and their exported symbols |
find_usages | Every reference to a symbol |
impact_analysis | Blast radius of changing a symbol, via the call graph |
explain_file | A file's purpose, exports, and key dependencies — no source |
list_projects | Which indexed projects this server serves |
MCP tools reference →
Safety
Redaction. Opt-in scrubbing of secrets and PII before a request leaves your
machine — private keys, JWTs, API keys (OpenAI, Anthropic, Stripe, GitHub,
Slack, AWS, Google), emails, Luhn-validated card numbers, SSNs, and phone
numbers, by regex; names and locations via local spaCy NER when the pii extra
is installed. Toggle it in the extension's chat panel; preview any string with
sema redact (reads STDIN only, so nothing lands in your shell history).
pip install 'sema-mcp[pii]' && python -m spacy download en_core_web_sm
echo "text" | sema redact
Agent permissions. Claude Code and Codex pause protected actions for an
inline Allow / Reject decision in the chat, or run in a clearly marked
bypass mode inside a trusted sandbox. Each provider keeps its own choice.
DevOps guard. Point an AI at kubectl, Terraform, AWS CLI, or Helm and sema
sits in between. Every command is classified and secret-redacted before it
runs, never after:
- Safe — read-only commands run immediately (and are still audited).
- Needs approval — mutations are held with an approval id until you
release them. Approvals are per-command and one-shot; the AI can never approve
its own held actions.
- Prohibited —
terraform destroy, force-deletes, deleting a
cluster-critical namespace, root-account deletion: refused outright, no
exceptions.
Enforcement is not documentation — sema devops install-shims puts wrappers on
your PATH that fail closed if sema isn't reachable. Everything lands in an
append-only, redacted audit log.
sema devops install-shims # put the guard on PATH
sema devops pending # what's waiting for you
sema devops approve <id> # release one held command
sema devops log # the audit trail
DevOps guard →
Keeping things current
sema update --check # show installed Claude/Codex/opencode/Grok versions
sema update # run every installed agent's official updater
sema update --provider codex # update one agent only (repeatable)
sema self-update # update sema itself
The extension exposes the same workflow under Manage → Update agent CLIs….
Reload VS Code afterwards so its model picker reflects the installed CLI.
Documentation
Start here: Installation · sema for VS Code · Terminal app · CLI reference
License
MIT — see LICENSE. Copyright (c) 2026 Masih Moloodian.
Masih Moloodian · [email protected] · Issues
