opus mcp human-invoked

Quick reference

Field	Value
Command	/brewcode:semble [status|setup|resume|enable|disable|reindex|optimize|update|remove|purge]
Arguments	a mode keyword, or free text in RU/EN — empty input is always status
Model	opus
Tools	Read, Bash, AskUserQuestion
MCP server	semble_code, registered at user scope, pin semble[mcp]==0.5.2

What it does

semble is the lifecycle router for semble_code — a semantic code-search MCP server that gives Claude two tools: mcp__semble_code__search (find code by intent) and mcp__semble_code__find_related (neighbors of a known location). The skill never edits code itself; it installs the prerequisite, registers the MCP server, wires a project rule and hooks, and migrates project agents so they can call the tools.

It always prints the current state before changing anything. Every mutation goes through a script under scripts/ — the skill only decides which one to run and reports the result.

Semble has no Homebrew formula of its own. The skill installs uv via brew (a machine-level step gated by an explicit confirmation) and then runs the pinned uvx --from 'semble[mcp]==0.5.2' semble --content code config — never a floating version.

When to use

Situation	Command
First time on a project, nothing wired yet	/brewcode:semble setup
Just reloaded Claude Code after setup	/brewcode:semble resume
Check current state, no changes	/brewcode:semble (empty input)
Something looks off, want a diagnostic	/brewcode:semble optimize
A newer semble[mcp] pin is approved	/brewcode:semble update
Turn search off without deleting anything	/brewcode:semble disable
One repo’s index looks stale	/brewcode:semble reindex
Free-text works too, RU or EN	/brewcode:semble переиндексируй
Remove the wiring, keep or drop pieces	/brewcode:semble remove
Wipe everything, including the cache	/brewcode:semble purge

Example

/brewcode:semble setup

uv missing — plan: brew install uv; uvx --from 'semble[mcp]==0.5.2' semble --help
[AskUserQuestion] Install uv via Homebrew now?  -> Install
✅ uv resolved, pin 0.5.2 confirmed
✅ docs cache root reserved (RESERVED-FOR-DOCS.txt)
✅ semble_code registered at user scope

Reload Claude Code (new session), then run: /brewcode:semble resume
Checkpoint: /abs/project/root/.claude/semble/state.json

After a fresh session:

/brewcode:semble resume

smoke query ok — cold index built in 23s, 7.6 MiB on disk
rule + hooks + permissions installed, 2 project agents migrated
phase: ready

Subsequent searches are sub-second and require the absolute repo path:

{"query": "how sessions are persisted", "repo": "/abs/project/root", "top_k": 5}

{"results": [
  {"file_path": "src/store/session.ts", "start_line": 41, "end_line": 58, "score": 0.83}
]}

Workflow

Technical details

Modes

Mode	Effect	Mutates
status	full report: prereqs, MCP, cache, guidance, agents, coverage, state	no
setup	install uv, register semble_code at user scope, checkpoint for reload	yes
resume	after reload: smoke query, rule + hooks + permissions, agent migration	yes
enable	turn back on: verify, warm, phase -> ready	yes
disable	enabled=false — hooks go silent, nothing deleted	yes
reindex	delete exactly this repo’s cache dir (confirmed), then warm	yes
warm	free-text intent (“warm”, “прогрей”) — pre-builds the index, deletes nothing	yes (cache write only)
optimize	read-only audit fan-out with concrete recommendations	no
update	compare the recorded pin against 0.5.2, re-register if different	yes
remove	four flavours: integration / mcp / cli / purge	yes
purge	everything, including the code cache root — typed confirmation required	yes

Prerequisites

Package	Required?	If declined or impossible
uv / uvx (brew install uv)	required — setup asks first, stops on decline	manual fallback curl -LsSf https://astral.sh/uv/install.sh | sh is printed, never run
coreutils (brew install coreutils -> gtimeout)	optional — offered only when no timeout/gtimeout binary exists and brew does	nothing breaks: sc_timeout keeps its pure-bash watchdog, every shell-out stays bounded either way

semble-install.sh takes one of check \| uv \| coreutils \| semble \| all — all runs them in that order and is what setup calls.

What setup installs

Surface	Location
MCP server	~/.claude.json .mcpServers.semble_code, user scope — -s user is mandatory, the CLI default is local
Command	uvx --from 'semble[mcp]==0.5.2' semble --content code config
Code cache root	absolute SEMBLE_CACHE_LOCATION: macOS ~/Library/Caches/semble-code / Linux ${XDG_CACHE_HOME:-~/.cache}/semble-code
Docs cache root	same path with a semble-docs leaf — created empty, reserved, never registered
State	<repo>/.claude/semble/state.json
Rule	<repo>/.claude/rules/semble-first.md
Hooks	SessionStart + a PreToolUse advisory reminder
Agents	project .claude/agents/**/*.md get the two tool names added to tools:; global agents are never touched

Reload boundary

A newly registered MCP server is not usable until a new Claude Code session. setup writes the checkpoint and stops there — it never claims success it cannot verify. /brewcode:semble resume continues at the smoke query in the new session.

Tool contract

Both mcp__semble_code__search and mcp__semble_code__find_related require an absolute repo argument — it is never inferred. Results carry file_path, start_line, end_line, score and optional content — there is no line field. Defaults: top_k=5, max_snippet_lines=10.

Corpus and coverage

Honest limits

Fact	Consequence
No watcher, no daemon	The index is built inside a tool call and cached; staleness is re-checked per call. Nothing runs in the background.
Every shell-out is time-bounded, with or without coreutils	sc_timeout uses timeout/gtimeout when a binary is present and a pure-bash watchdog when none is — the report’s timeout.bounded is always true. coreutils only upgrades which binary enforces the bound; it is never required and never a reason a run can fail.
Cold cache = slow first query	The embedding model download can take up to 600s and fails offline with a cold HuggingFace cache.
Docs corpus is reserved, not registered	The per-repo cache key does not encode content type — mixing code and docs in one cache dir would collide and invalidate on every call, so the docs root exists empty and untouched.
semble clear index wipes everything under the cache root	There is no per-repo rebuild CLI; reindex deletes exactly one resolved <code root>/<64-hex> directory, guarded and confirmed.
Windows is unsupported	The skill refuses every mutation on a non-macOS/Linux platform.

Removal flavours

Flavour	Rule / hooks	MCP	Agent frontmatter	Cache	uv tool
integration	removed	kept	semble entries removed	kept	kept
mcp	kept	removed	kept	kept	kept
cli	kept	kept	kept	kept	uninstalled
purge	removed	removed	removed	code root removed	typed confirmation

Measured on this repo

Metric	Value
Cold index build	23s
Cache size on disk	7.6 MiB
Subsequent queries	sub-second