Skip to main content
skill CX Codex

semble — Claude Code skill: code search and installation

The semble Claude Code skill searches code by behavior or symbol name. It activates when an agent needs to locate an implementation or find code similar to a known snippet.

MIT 234 installs ★ 61 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add akillness/jeo-skills --skill semble -a claude-code
Open on GitHub

What semble does

semble indexes a local or remote repository and returns matching snippets with file paths and line numbers. Queries can describe behavior in plain language, name a symbol, or point to a known file location to find semantically similar code. MCP use with Claude Code requires uv; no API key or GPU is needed.

The skill searches code; it does not read whole files, list directories, or run tests. For exact-string and regex searches, the source recommends Grep. Install the skill in Claude Code with npx skills add akillness/jeo-skills --skill semble -a claude-code; the file goes to ~/.claude/skills/semble/SKILL.md.

What it helps with

  • locate an implementation from a behavior description
  • find a symbol without knowing its file
  • discover code similar to a known snippet
  • search a remote Git repository without cloning it

Example prompts for the agent

  • Find how this project handles request throttling.
  • Search the repository for the symbol save_pretrained.
  • Find code similar to the section at src/auth.py, line 42.

How to install semble

1Skills CLI (Vercel)

npx skills add akillness/jeo-skills --skill semble -a claude-code

2Manually: put the files in place

~/.claude/skills/semble/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/semble/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about semble

How do I install semble in Claude Code?

Run npx skills add akillness/jeo-skills --skill semble -a claude-code. The skill is installed at ~/.claude/skills/semble/SKILL.md.

What does semble do?

It searches local and remote repositories using a natural-language query or symbol name, and can find semantically similar snippets. Results include file paths and line numbers.

What does semble need to work?

Installing the skill requires npx. MCP integration with Claude Code requires uv; no API key or GPU is needed.

Source text

SKILL.md · MIT
---
name: semble
description: >
  Fast, accurate code search for AI agents using ~98% fewer tokens than grep+read.
  Indexes any local or remote repository in under a second (~250ms on CPU, no GPU or API key needed).
  Supports natural-language and symbol queries, semantic similar-code discovery, and MCP server
  integration for Claude Code, Codex, Cursor, and OpenCode. Python library available for programmatic
  use. Triggers on: semble, code search, semantic code search, semble search, token-efficient search,
  find code, code search mcp, agent code search, semble find-related, semble savings.
allowed-tools: Read Write Bash Grep Glob WebFetch
metadata:
  tags: semble, code-search, semantic-search, mcp, token-efficient, agent-tools, python, cli, codebase-navigation
  platforms: Claude Code, Codex CLI, Gemini CLI, OpenCode, Cursor
  keyword: semble
  version: latest
  source: MinishLab/semble
  license: MIT
---

# semble — Fast Token-Efficient Code Search for Agents

> ~98% fewer tokens than grep+read. Index in ~250ms. Query in ~1.5ms. No GPU, no API key.

Semble returns only the relevant code snippets agents need, without grepping full files or reading directories. A natural-language or symbol query like `"authentication flow"` or `"save_pretrained"` returns exact chunks with file paths and line ranges — nothing more.

## Installation

### MCP (Claude Code — recommended)
```bash
# Requires uv: https://docs.astral.sh/uv/getting-started/installation/
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
```

### MCP (Codex)
```bash
codex mcp add semble -- uvx --from "semble[mcp]" semble
```

### MCP (Cursor / OpenCode)
Register `semble` as a local MCP server in your editor's MCP server settings UI with command `uvx` and args `["--from", "semble[mcp]", "semble"]`.

### CLI / pip
```bash
pip install semble        # pip
uv tool install semble    # uv (recommended for CLI use)
```

### Skill (any platform)
```bash
npx [email protected] add https://github.com/akillness/jeo-skills --skill semble
```

## When to use

- Search a codebase by describing behavior in natural language (`"how is rate limiting handled"`)
- Look up a symbol or identifier without knowing the exact file (`"save_pretrained"`)
- Discover code semantically similar to a known location (`find-related`)
- Give an agent token-efficient access to any repo via MCP instead of letting it grep/read full files
- Index a remote git repo without cloning first

## Do not use when

- You need to read a full file or directory listing → use native `Read`, `Glob` tools
- You need regex or exact-string search → `Grep` is more appropriate
- The repo is too small to justify indexing (a few files) — just read them directly
- You need to run tests, build, or execute code — this is a search-only tool

## CLI usage

```bash
# Natural-language search in a local repo
semble search "authentication flow" ./my-project

# Symbol search
semble search "save_pretrained" ./my-project

# Search with a limit on returned chunks
semble search "save model to disk" ./my-project --top-k 10

# Search a remote git repo (no clone needed)
semble search "save model to disk" https://github.com/MinishLab/model2vec

# Find semantically similar code given a known file+line
semble find-related src/auth.py 42 ./my-project

# Show token savings vs grep+read for the last query
semble savings
semble savings --verbose
```

## Python library

```python
from semble import SembleIndex

# Index local directory
index = SembleIndex.from_path("./my-project")

# Index remote repository (no clone required)
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Natural-language or symbol query
results = index.search("save model to disk", top_k=3)

# Find semantically similar code to a known chunk
related = index.find_related(results[0], top_k=3)

# Inspect results
result = results[0]
print(result.chunk.file_path)   # "model2vec/model.py"
print(result.chunk.start_line)  # 127
print(result.chunk.end_line)    # 150
print(result.chunk.content)     # the function/class body
```

## AGENTS.md / CLAUDE.md integration

Add this section to your project's `AGENTS.md` or `CLAUDE.md` to enable semble for all agents:

````markdown
## Code Search

Use `semble search` to find code by describing what it does or naming a symbol, instead of grep:

```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10
```

Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):

```bash
semble find-related src/auth.py 42 ./my-project
```

`path` defaults to the current directory when omitted; git URLs are accepted.

If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
````

For Claude Code sub-agents, initialize once in the project root:
```bash
semble init
```

## Performance benchmarks

| Metric | Semble | grep+read |
|--------|--------|-----------|
| Indexing speed | ~250ms | n/a |
| Query speed | ~1.5ms | varies |
| Token use at 94% recall | ~2k tokens | ~100k tokens |
| NDCG@10 | 0.854 | — |
| vs 137M-param CodeRankEmbed | 99% quality | — |
| Indexing vs transformer | 218× faster | — |

## Operating rules

1. Prefer MCP installation for interactive agent use; prefer CLI/pip for scripting and CI.
2. Use `--top-k` to limit results and keep context small — default is often too generous for agent prompts.
3. Use `find-related` after `search` when you need to expand from one known chunk into similar code.
4. Use `semble init` in project roots to pre-warm the index for Claude Code sub-agents.
5. If `semble` is not on `$PATH`, replace with `uvx --from "semble[mcp]" semble` in scripts.
6. Treat semble as the first pass — read full files only when the returned chunk is insufficient context.

## Examples

```bash
# Search for how a feature is implemented
semble search "rate limiting middleware" ./api-service

# Find all code related to database migrations
semble search "database migration" ./backend --top-k 5

# Explore similar code patterns near a known function
semble find-related src/middleware/auth.py 88 ./api-service

# Index and query a remote library without cloning
semble search "tokenizer padding" https://github.com/huggingface/transformers
```

Source: [MinishLab/semble](https://github.com/MinishLab/semble) — MIT License

© akillness · MIT · akillness/jeo-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set99

The whole set →
payloadcms Walks the agent through Payload CMS work in a repo: bootstrapping an app, changing collection schemas, debugging the admin panel or API, preparing migrations. CX Codex +1 253installs zeude The zeude Claude Code skill tracks team usage and syncs shared settings. It suggests relevant skills as developers enter prompts. CX Codex +1 252installs hyperfine-benchmarking hyperfine-benchmarking — a skill that runs commands with warmup cycles and collects timing statistics. Compare tool variants or validate performance changes before committing, with exportable evidence. CX Codex +1 251installs ghgrab The ghgrab skill lets an agent find and download chosen GitHub files, folders, and release assets from the terminal without cloning the whole repository. CX Codex +1 251installs react-bits Steers an agent through react-bits: pick dependencies, drop an animated component into a React project, fix GSAP and Three.js leaks, or send your own component upstream. CX Codex +1 211installs deep-dive deep-dive — a two-stage skill: three parallel lanes trace why something broke, then a requirements interview starts from those findings. Built for bugs and changes in code you don't know yet. CX Codex +1 177installs spec-kit Installs GitHub's specify CLI, bootstraps a spec-driven project for your agent, and runs the /speckit.* pipeline from constitution to implementation. CX Codex +1 167installs academic-research academic-research sorts a research topic or paper draft into one of several linked academic workflows, from literature discovery to peer review. The skill itself decides which branch and mode fit the request. CX Codex +1 148installs

Project sponsors

Companies that keep this analytics open