Skip to content

installation.md

Latest commit

 

History

History
528 lines (391 loc) · 13.4 KB

installation.md

File metadata and controls

528 lines (391 loc) · 13.4 KB
Raw

Installation

Recommended: semble install

The interactive installer detects your installed agents and configures any combination of four 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.
  • Skill: installs a semble skill plus a one-line pointer to it in AGENTS.md / CLAUDE.md, as an alternative to the full block. Off by default.

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, Command Code, Antigravity, ZCode, Grok Build, Qwen Code, Cline, and Kilo 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.

Unattended install

For sandboxed or scripted environments, pass --agent to skip the interactive prompts:

semble install --agent claude pi --type mcp subagent --yes
  • --agent — one or more agent ids (see the list above; use the lowercase form, e.g. claude, codex, pi).
  • --type — one or more of mcp, instructions, subagent, skill, or all (default: all but skill). Requires --agent.
  • -y/--yes — skip the confirmation prompt. Requires --agent for a fully non-interactive run.

semble uninstall accepts the same flags.

Keeping installed configuration up to date

The MCP server config, AGENTS.md/CLAUDE.md instructions, and sub-agent files that semble install writes all pin uvx to the exact semble version you have installed (semble[mcp]==X.Y.Z), so agents keep calling the version the instructions were written for rather than whatever is newest on PyPI. After upgrading (uv tool upgrade semble or pip install --upgrade semble), rerun semble install. This is idempotent and rewrites the pin (and anything else that changed) in place for every agent you select.

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 (the backwards-compatible MCP config path read by all Reasonix versions):

{
  "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"]
 }
 }
}
Antigravity

Add to ~/.gemini/config/mcp_config.json:

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

Add to ~/.commandcode/mcp.json:

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

Or use the CLI:

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

Add to ~/.zcode/cli/config.json under the nested mcp.servers key (or use Settings -> MCP Servers -> Full configuration mode):

{
  "mcp": {
    "servers": {
      "semble": {
        "command": "uvx",
        "args": ["--from", "semble[mcp]", "semble"],
        "type": "stdio"
      }
    }
  }
}
Grok Build

Add to ~/.grok/config.toml:

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

Add to ~/.qwen/settings.json:

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

Add to ~/.cline/data/settings/cline_mcp_settings.json (shared by the Cline IDE extensions and CLI):

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

Or use the CLI:

cline mcp add semble --yes -- uvx --from "semble[mcp]" semble
Kilo Code

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

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

The MCP server indexes each requested content selection on first use and caches it separately. Searches default to code; append --content docs, --content config, or --content all to the server command to change that default. The content argument on an individual MCP search overrides it. For example, in Claude Code:

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

Indexes stay in memory for the lifetime of the server. To free memory while idle, set SEMBLE_MCP_IDLE_TIMEOUT to a number of seconds; indexes unused for that long are dropped from memory and reloaded from the disk cache on the next search.

Shared server (HTTP)

By default each agent session starts its own semble process. To share one server (and one copy of the model and indexes) across sessions, start it yourself over HTTP:

uvx --from "semble[mcp]" semble --http --port 8000

It listens on 127.0.0.1 only. Then point your agents at http://127.0.0.1:8000/mcp instead of the uvx command:

# Claude Code
claude mcp add --transport http semble -s user http://127.0.0.1:8000/mcp
// Cursor (~/.cursor/mcp.json)
{ "mcpServers": { "semble": { "url": "http://127.0.0.1:8000/mcp" } } }
# Codex (~/.codex/config.toml)
[mcp_servers.semble]
url = "http://127.0.0.1:8000/mcp"

Relative repo paths resolve against the directory the server was started in, so agents should pass absolute paths. semble install only sets up the stdio server.

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 --max-snippet-lines 10  # first 10 lines only, concise
semble search "save_pretrained" ./my-project                          # full chunk content
semble search "save model to disk" ./my-project --top-k 10           # more results
​```

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. Pass several paths or URLs to search related repos together, e.g. when this project calls a service defined in a sibling repo. Result paths are then prefixed with the repo name and the output includes a `repos` map from prefix to location:

```bash
semble search "invoice endpoint" ./service-a ../service-b

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. Navigate directly to the returned file and line — do not re-search or grep for the same content.
  4. Optionally use semble find-related with a promising result's file_path and line to discover related implementations.
  5. If the answer may live in a dependent or sibling repo, pass all relevant repo paths to one semble search call.
  6. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function).

### Sub-agent

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

| Agent | 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` |
| Codex | `codex.toml` | `~/.codex/agents/semble-search.toml` |
| Reasonix | `reasonix.md` | `~/.reasonix/skills/semble-search.md` |
| Pi | `pi.md` | `~/.pi/agents/semble-search.md` |
| Command Code | `commandcode.md` | `~/.commandcode/agents/semble-search.md` |
| Antigravity | `antigravity.md` | `~/.gemini/config/skills/semble-search/SKILL.md` |
| ZCode | `zcode.md` | `~/.zcode/agents/semble-search.md` |
| Grok Build | `grok.md` | `~/.grok/agents/semble-search.md` |
| Qwen Code | `qwen.md` | `~/.qwen/agents/semble-search.md` |
| Kilo Code | `kilo.md` | `~/.config/kilo/agents/semble-search.md` |

### Skill

For harnesses that support [Agent Skills](https://agentskills.io), you can install a `semble` skill instead of the AGENTS.md block. Copy [`src/semble/agents/skill.md`](../src/semble/agents/skill.md) to the destination below as `SKILL.md`:

| Agent | Destination |
|---|---|
| Claude Code | `~/.claude/skills/semble/SKILL.md` |
| Qwen Code | `~/.qwen/skills/semble/SKILL.md` |
| Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Pi, Kilo Code | `~/.agents/skills/semble/SKILL.md` |

`~/.agents/skills` is shared between agents, so uninstalling the skill for one of them removes it for all of them.

Agents rarely load a skill on their own, so also add this line to your AGENTS.md / CLAUDE.md (`semble install` does this for you):

```markdown
Use the `semble` skill for code search instead of Grep or Glob.