diff --git a/README.md b/README.md index 5037d539..dabd5999 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ -Semble is a code search library built for agents. It returns the exact code snippets they need instantly, using ~98% fewer tokens than grep+read. Indexing and searching a full codebase end-to-end takes under a second, with ~200x faster indexing and ~10x faster queries than a code-specialized transformer, at 99% of its retrieval quality (see [benchmarks](#benchmarks)). Everything runs on CPU with no API keys, GPU, or external services. Run it as an MCP server or call it from the shell via AGENTS.md and any agent (Claude Code, Cursor, Codex, OpenCode, etc.) gets instant access to any repo. +Semble is a code search library built for agents. It returns the exact code snippets they need instantly, using ~98% fewer tokens than grep+read. Indexing and searching a full codebase end-to-end takes under a second, with ~200x faster indexing and ~10x faster queries than a code-specialized transformer, at 99% of its retrieval quality (see [benchmarks](#benchmarks)). Everything runs on CPU with no API keys, GPU, or external services. Use it as an MCP server, a CLI tool via AGENTS.md, or a dedicated sub-agent, and any coding agent (Claude Code, Cursor, Codex, OpenCode, etc.) gets instant access to any repo. ## Quickstart diff --git a/docs/installation.md b/docs/installation.md index 7ea5dca7..d627ed53 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -21,7 +21,9 @@ To undo: semble uninstall ``` -Supported agents: Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Codex, VS Code, Windsurf, and Zed. +Supported agents: Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Codex, VS Code, Windsurf, Zed, Reasonix, and Pi. + +> **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`. --- @@ -198,6 +200,48 @@ Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project): +
+Reasonix + +Add to `~/.reasonix/config.json` (the backwards-compatible MCP config path read by all Reasonix versions): + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--from", "semble[mcp]", "semble"] + } + } +} +``` + +
+ +
+Pi + +First install the Pi MCP extension (one-time prerequisite): + +```bash +pi install npm:pi-mcp-extension +``` + +Then add to `~/.pi/agent/mcp.json`: + +```json +{ + "mcpServers": { + "semble": { + "command": "uvx", + "args": ["--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: ```bash @@ -250,7 +294,9 @@ If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its plac ### Sub-agent -For harnesses that support sub-agents (Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot), 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: +For harnesses that support sub-agents (Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Reasonix, Pi), 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 | |---|---|---| @@ -260,3 +306,5 @@ For harnesses that support sub-agents (Claude Code, Cursor, Gemini CLI, Kiro, Op | 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` | +| Reasonix | `reasonix.md` | `~/.reasonix/skills/semble-search.md` | +| Pi | `pi.md` | `~/.pi/agents/semble-search.md` | diff --git a/src/semble/agents/pi.md b/src/semble/agents/pi.md new file mode 100644 index 00000000..2071c275 --- /dev/null +++ b/src/semble/agents/pi.md @@ -0,0 +1,40 @@ +--- +name: semble-search +description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question. +--- + +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 +``` + +Results are cached automatically on first run and invalidated 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. diff --git a/src/semble/agents/reasonix.md b/src/semble/agents/reasonix.md new file mode 100644 index 00000000..94f42c57 --- /dev/null +++ b/src/semble/agents/reasonix.md @@ -0,0 +1,42 @@ +--- +name: semble-search +description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over bash/grep for any semantic or exploratory question. +runAs: subagent +allowed-tools: bash, read_file +--- + +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 +``` + +Results are cached automatically on first run and invalidated 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 bash/grep only when you need exhaustive literal matches or quick confirmation of an exact string. diff --git a/src/semble/installer/agents.py b/src/semble/installer/agents.py index 14fb533e..0f57c52e 100644 --- a/src/semble/installer/agents.py +++ b/src/semble/installer/agents.py @@ -215,6 +215,27 @@ def _vscode_mcp_path() -> Path: mcp=McpConfig(_HOME / ".config" / "zed" / "settings.json", "context_servers", _ZED_SERVER_CONFIG), instructions_path=None, ), + AgentTarget( + id="reasonix", + display_name="Reasonix", + binary="reasonix", + config_dir=_HOME / ".config" / "reasonix", + # ~/.reasonix/config.json is the legacy v0.x path still read by v1.x for backwards compat. + # The v1.x canonical config is ~/.config/reasonix/config.toml ([[plugins]]), but the JSON + # path requires no special TOML handling and works for new users who have never had v0.x. + mcp=McpConfig(_HOME / ".reasonix" / "config.json", "mcpServers", _BARE_STDIO_SERVER_CONFIG), + instructions_path=_HOME / ".config" / "reasonix" / "REASONIX.md", + subagent_path=_HOME / ".reasonix" / "skills" / "semble-search.md", + ), + AgentTarget( + id="pi", + display_name="Pi", + binary="pi", + config_dir=_HOME / ".pi", + mcp=McpConfig(_HOME / ".pi" / "agent" / "mcp.json", "mcpServers", _BARE_STDIO_SERVER_CONFIG), + instructions_path=None, + subagent_path=_HOME / ".pi" / "agents" / "semble-search.md", + ), ] diff --git a/src/semble/version.py b/src/semble/version.py index 0c3f13b4..9bfefb0c 100644 --- a/src/semble/version.py +++ b/src/semble/version.py @@ -1,2 +1,2 @@ -__version_triple__ = (0, 3, 2) +__version_triple__ = (0, 3, 3) __version__ = ".".join(map(str, __version_triple__)) diff --git a/tests/test_installer.py b/tests/test_installer.py index fb27353a..6e4de28d 100644 --- a/tests/test_installer.py +++ b/tests/test_installer.py @@ -125,7 +125,13 @@ def test_merge_mcp_errors(claude_agent, content): @pytest.mark.parametrize( ("agent_id", "key"), - [("zed", "context_servers"), ("windsurf", "mcpServers"), ("copilot", "mcpServers")], + [ + ("zed", "context_servers"), + ("windsurf", "mcpServers"), + ("copilot", "mcpServers"), + ("reasonix", "mcpServers"), + ("pi", "mcpServers"), + ], ) def test_merge_mcp_writes_under_agent_key(tmp_path, agent_id, key): """merge_mcp writes the semble entry under each agent's own top-level MCP key."""