# Semble — Code Search for Agents (MCP + CLI)

> Semble is an agent-first code search CLI/MCP that returns only relevant chunks, using ~98% fewer tokens than grep+read and tracking savings locally.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

1. Install:
   ```bash
   pip install semble
   # or: uv tool install semble
   ```
2. Search:
   ```bash
   semble search "authentication flow" ./my-project
   semble find-related src/auth.py 42 ./my-project
   semble savings
   ```

## Intro

Semble is an agent-first code search CLI/MCP that returns only relevant chunks, using ~98% fewer tokens than grep+read and tracking savings locally.

- **Best for:** agents and devs who need fast, token-light code discovery across large repos
- **Works with:** Python; CLI + optional MCP integration; Claude Code/Codex/Cursor via shell or MCP client
- **Setup time:** 5–15 minutes

## Practical Notes

- Quant: the README headline says it uses **~98% fewer tokens** than grep+read on average.
- Quant: the sample savings table shows ~**58.4k tokens saved (95%)** “Today” and ~**1.2M tokens (89%)** “All time”.

## Main

Two reliable integration patterns:

1. **CLI-first**: use `semble search` to get narrow chunks, then open full files only when needed.
2. **Agent workflows**: copy the README’s “Code Search” snippet into `AGENTS.md` so agents consistently prefer Semble over full-file reads.

If you run Semble as MCP, keep your token budget stable: the agent should query Semble for candidates, then request full files only for the final few hits.

### FAQ

**Q: Do I need an API key or GPU?**
A: No—README describes CPU-only local runs with no external services required.

**Q: How do I measure impact?**
A: Use `semble savings` and compare before/after over a week of real work.

**Q: When does grep still matter?**
A: Exact string checks and exhaustive literal matches; Semble is for fast semantic discovery.

## Source & Thanks

> Source: https://github.com/MinishLab/semble
> License: MIT
> GitHub stars: 794 · forks: 61

---

<!-- ZH -->

## 快速使用

1. 安装：
   ```bash
   pip install semble
   # 或：uv tool install semble
   ```
2. 检索：
   ```bash
   semble search "authentication flow" ./my-project
   semble find-related src/auth.py 42 ./my-project
   semble savings
   ```

## 简介

Semble 是为 Agent 设计的代码检索 CLI/MCP，只返回相关片段，平均可比 grep+read 少用约 98% tokens，并可用 `semble savings` 统计节省，无需 API key。

- **适合谁：** 需要在大仓库里快速、低 token 定位代码的 agent 与开发者
- **可搭配：** Python；既可 CLI，也可 MCP；适配 Claude Code/Codex/Cursor 等
- **准备时间：** 5–15 分钟

## 实战建议

- 量化信息：README 标注平均可比 grep+read **少用约 98% tokens**。
- 量化信息：示例统计显示“Today”约 **58.4k tokens（95%）**，All time 约 **1.2M tokens（89%）**。

## 主要内容

两个更稳的落地方式：

1. **CLI 优先**：用 `semble search` 先拿到很窄的代码片段，只有必要时再打开完整文件。
2. **写进团队规则**：把 README 的 “Code Search” 片段写入 `AGENTS.md`，让 agent 默认优先用 Semble 而不是整文件读取。

如果用 MCP 方式接入，建议保持固定 token 预算：先让 agent 用 Semble 产出候选，再只对少数命中做全文读取。

### FAQ

**需要 API key 或 GPU 吗？**
答：不需要；README 描述为 CPU 本地运行，不依赖外部服务。

**怎么衡量效果？**
答：用 `semble savings` 做周尺度对比，而不是单次体验。

**grep 什么时候仍然必要？**
答：做精确字符串确认或穷举匹配时；Semble 更适合语义检索与定位。

## 来源与感谢

> Source: https://github.com/MinishLab/semble
> License: MIT
> GitHub stars: 794 · forks: 61


---
Source: https://tokrepo.com/en/workflows/semble-code-search-for-agents-mcp-cli
Author: MCP Hub