Skip to content

installation.md

Latest commit

 

History

History
395 lines (292 loc) · 9.63 KB

installation.md

File metadata and controls

395 lines (292 loc) · 9.63 KB
Raw

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, Command Code, Antigravity, and ZCode.

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, or all (default: all). 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"
      }
    }
  }
}

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

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.

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. 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), 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.

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