---
id: semble
version: "0.5.5"
license: MIT License Copyright (c) 2026 Thomas van Dongen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# semble — Fast and Accurate Code Search for Agents

License: permissive · Maintenance: active · Downloads: 131.2K/mo

## What it is and what it does

Semble is a code search engine designed for AI agents and developers. It builds an index of a codebase using embeddings from model2vec, then answers natural-language queries by returning only the relevant code snippets—not full files. The library runs entirely on CPU with no external APIs or GPU required, and caches both indexes and the embedding model locally.

You can use Semble three ways: as an MCP server (for Claude Code, Cursor, Codex, and other agents), as a CLI tool for one-off searches, or as a Python library for programmatic access. It reads .gitignore and .sembleignore to control which files are indexed, and automatically skips well-known non-source directories. The fact sheet indicates indexing takes roughly 500 ms for an average repo and queries return in roughly 1 ms, with token savings estimated at ~99% compared to reading full files.

Use it for:

- Integrate code search into Claude Code, Cursor, or other MCP-compatible agents so they can find relevant snippets without grepping or reading full files.
- Build a CLI tool to search a remote repository (cloned on demand) or local codebase without setting up a full development environment.
- Use as a Python library to add semantic code search to custom tooling, RAG pipelines, or agent workflows.
- Quickly locate code patterns (e.g., 'how is authentication handled?') across unfamiliar codebases during onboarding or code review.
- Track token savings across searches to quantify efficiency gains when using Semble instead of traditional grep-and-read workflows.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Semble is a code search library that indexes and searches codebases using embeddings, returning relevant code snippets in response to natural-language queries with minimal token overhead.

Yes. Semble is actively maintained, has low install friction, carries a permissive MIT license, and solves a real problem for agent-assisted development. It has no known vulnerabilities and supports current Python versions (3.10–3.13). Install it if you work with coding agents or need fast, token-efficient code search; the MCP integration and CLI are both straightforward to set up.

## Install

pip install semble
uv add semble
poetry add semble

## Installing semble

Before you install: Low friction: pure Python wheel with 7 runtime dependencies including model2vec for embeddings and questionary for CLI prompts. Active maintenance—released 2 days ago with 5879 repository stars and continuous commits.

License in practice: MIT License permits unrestricted commercial and private use, modification, and redistribution with only attribution and license-text retention required.

Quickstart:

pip install semble

from semble import SembleIndex

index = SembleIndex.from_path("./my-project")
results = index.search("authentication flow")
for result in results:
    print(result)

Requires Python 3.10 or later. On first use, downloads an embedding model from Hugging Face (one-time, requires network access).

Verify before relying:

- Whether the embedding model download size and cache footprint are acceptable for resource-constrained environments.
- Performance characteristics when indexing very large codebases (millions of lines) or with many concurrent searches.
- Compatibility and behavior with non-standard or mixed-language repositories.

## Package facts

- License: MIT License Copyright (c) 2026 Thomas van Dongen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 131.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

code search for agents, semantic code search, embedding-based code retrieval, mcp code search server, agent-friendly code indexing, fast codebase search, local code search no api, agent-integration, code-search, embeddings

[View on SkillFed](https://skillfed.io/packages/semble) · [View on PyPI](https://pypi.org/project/semble/)