Installation

Recommended: semble install

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

• MCP server: exposes Semble as a native tool your agent can call directly.
• AGENTS.md: adds a Semble usage guide to the 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, Pi, and Command Code.

Pi prerequisite: Pi requires the MCP extension to be installed 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 mcp add semble -s user -- uvx --from "semble[mcp]" semble

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

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

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

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

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

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

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

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

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

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

pi install npm:pi-mcp-extension

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

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

cmd mcp add --scope user semble -- uvx --from "semble[mcp]" semble

By default the MCP server indexes only code files. To also index documentation, config, or everything, append --content docs, --content config, or --content all to the server command. 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 or CLAUDE.md 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 for subsequent runs) and invalidated automatically 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. The index is built and cached automatically.
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

For harnesses that support sub-agents (Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Reasonix, Pi, Command Code), you can install a dedicated semble-search sub-agent. Copy the appropriate file from src/semble/agents/ 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.