Installation

Requirements

Python 3.10 or higher.
uv (recommended).
No GPU, API keys, or external services required. Runs fully on CPU.

Recommended: `semble install`

The interactive installer detects your installed agents and configures any combination of three integrations:

MCP server: exposes Semble as a native tool your agent can call directly.
Instructions: adds CLI usage guidance to your agent’s config file (CLAUDE.md, AGENTS.md, etc.).
Sub-agent: installs a dedicated semble-search sub-agent for harnesses that support it.

Install the CLI with uv, then run:

uv tool install semble
semble install

To undo:

semble uninstall

Supported agents: Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Codex, VS Code, Windsurf, Zed, Reasonix, and Pi.

Pi prerequisite: Pi requires the MCP extension before Semble can connect. Run pi install npm:pi-mcp-extension once, then semble install.

Manual setup

MCP server

Requires uv to be installed.

Claude Code

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

OpenCode

Add to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "semble": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project (or your user profile’s mcp.json):

{
  "servers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Kiro

Add to ~/.kiro/settings/mcp.json (or .kiro/settings/mcp.json in your project):

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json (or .zed/settings.json in your project):

{
  "context_servers": {
    "semble": {
      "source": "custom",
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Reasonix

Add to ~/.reasonix/config.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Pi

First install the Pi MCP extension (one-time prerequisite):

pi install npm:pi-mcp-extension

Then add to ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Content types

By default the MCP server indexes only code files. To also index documentation (markdown, rst, etc.), config files (yaml, toml, etc.), or everything, append --content to the server command. Valid values are code (default), docs, config, and all. For example, in Claude Code:

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble --content all

Instructions (AGENTS.md / CLAUDE.md)

Add the snippet below to your AGENTS.md, CLAUDE.md, GEMINI.md, or equivalent so your agent knows when and how to call the Semble CLI:

## Code Search

Use `semble search` to find code by describing what it does or naming a symbol/identifier, 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
```

The index is built on first run and cached automatically; it is invalidated when files change.

Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:

```bash
semble search "deployment guide" ./my-project --content docs
semble search "database host port" ./my-project --content config
semble search "authentication" ./my-project --content all
```

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.

### Workflow

1. Start with `semble search` to find relevant chunks.
2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
3. Inspect full files only when the returned chunk does not give enough context.
4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations.
5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.

Sub-agent

Sub-agents typically cannot call MCP tools directly. semble install handles this automatically. For manual setup, copy the appropriate file from the table below to your agent’s agents directory:

Pi prerequisite: Pi sub-agents require the Pi agents extension. Run pi install npm:pi-agents once before installing.

Agent	Source file	Destination
Claude Code	`claude.md`	`~/.claude/agents/semble-search.md`
Cursor	`cursor.md`	`~/.cursor/agents/semble-search.md`
Gemini CLI	`gemini.md`	`~/.gemini/agents/semble-search.md`
Kiro	`kiro.md`	`~/.kiro/agents/semble-search.md`
OpenCode	`opencode.md`	`~/.config/opencode/agents/semble-search.md`
GitHub Copilot	`copilot.md`	`~/.copilot/agents/semble-search.agent.md`
Reasonix	`reasonix.md`	`~/.reasonix/skills/semble-search.md`
Pi	`pi.md`	`~/.pi/agents/semble-search.md`

Source files are in src/semble/agents/ in the Semble repository.

Updating Semble

uv tool upgrade semble         # with uv
pip install --upgrade semble   # with pip
uv cache clean semble          # for MCP users (restart your MCP client after)