From f5e1685bcd04daa0d2e398fc4378f16c4ada3af5 Mon Sep 17 00:00:00 2001 From: Pringled Date: Thu, 28 May 2026 07:53:32 +0200 Subject: [PATCH 1/3] Update README --- README.md | 52 +++------------------------------------------------- 1 file changed, 3 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 42f20f2..2535d3a 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,8 @@ claude mcp add semble -s user -- uvx --from "semble[mcp]" semble See [MCP Server](#mcp-server) below for other harnesses (Cursor, Codex, OpenCode, etc.). + + ### AGENTS.md Add Semble usage instructions to your agent's context so it knows when and how to call the CLI. Install the Semble CLI, then add the snippet below to your `AGENTS.md` or `CLAUDE.md`: @@ -315,55 +317,7 @@ Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project): 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, or a combination, e.g. `--content code docs`. For example, in Claude Code: `claude mcp add semble -s user -- uvx --from "semble[mcp]" semble --content all`. - - -## Bash / AGENTS.md - -An alternative to MCP is to invoke Semble via Bash. Sub-agents cannot call MCP tools directly, so this is the only option for sub-agent support; it can also be used alongside MCP for the top-level agent. - -To add Bash support, append the following to your `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalent: - -```markdown -## 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 setup +## Sub-agent setup Claude Code, Gemini CLI, Cursor, OpenCode, GitHub Copilot CLI, and Kiro all support a dedicated semble search sub-agent. Run `semble init` once in your project root: From d461be2b86dc1bb29c158c329adea1b192362f84 Mon Sep 17 00:00:00 2001 From: Pringled Date: Thu, 28 May 2026 07:58:00 +0200 Subject: [PATCH 2/3] Update README --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 2535d3a..0f73313 100644 --- a/README.md +++ b/README.md @@ -477,6 +477,12 @@ After fusing, results are reranked with a set of code-aware signals: Because the embedding model is static with no transformer forward pass at query time, all of this runs in milliseconds on CPU. +Indexes are cached to disk automatically on the first search. On subsequent runs, Semble walks the file tree and compares modification times; if any file was added, removed, or changed, the index is fully rebuilt. In MCP mode, a file watcher detects changes and triggers a rebuild automatically so the index is always current within the same session. + +## Acknowledgements + +Thanks to [Greptile](https://greptile.com) for providing free access to their AI code review platform for open-source projects. + ## License MIT From 71b83f0c642d765cbf1e197864a2c9a2c0950898 Mon Sep 17 00:00:00 2001 From: Pringled Date: Thu, 28 May 2026 08:07:05 +0200 Subject: [PATCH 3/3] Update docs --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0f73313..81e9e2f 100644 --- a/README.md +++ b/README.md @@ -134,7 +134,7 @@ pip install --upgrade semble # with pip ## MCP Server -Semble can run as an MCP server so agents can search any codebase directly. Repos are cloned and indexed on demand, and indexes are cached for the lifetime of the session. Local paths are watched for file changes and re-indexed automatically. +Semble can run as an MCP server so agents can search any codebase directly. Repos are cloned and indexed on demand. Indexes are persisted to the OS cache folder and reused across sessions; local paths are watched for file changes and re-indexed automatically. ### Setup @@ -481,7 +481,7 @@ Indexes are cached to disk automatically on the first search. On subsequent runs ## Acknowledgements -Thanks to [Greptile](https://greptile.com) for providing free access to their AI code review platform for open-source projects. +Thanks to [Greptile](https://greptile.com) for providing free access to their AI code review platform. ## License