semble 0.3.2__tar.gz → 0.3.4__tar.gz

{semble-0.3.2 → semble-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semble
-Version: 0.3.2
+Version: 0.3.4
 Summary: Fast and Accurate Code Search for Agents
 Author-email: Thomas van Dongen <thomasvdongen@proton.me>, Stéphan Tulkens <stephantul@gmail.com>
 License: MIT License
@@ -98,7 +98,7 @@ Dynamic: license-file
 
 </div>
 
-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](#mcp-server) or call it from the shell via [AGENTS.md](#agentsmd) 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
 
@@ -194,23 +194,43 @@ Semble also always skips a set of well-known non-source directories regardless o
 `semble savings` shows how many tokens semble has saved across all your searches:
 
 ```bash
-semble savings           # summary by period
-semble savings --verbose # also show breakdown by call type
+semble savings
 ```
 
 ```
   Semble Token Savings
-  ════════════════════════════════════════════════════════════════
-  Period        Calls   Savings
-  ────────────────────────────────────────────────────────────────
-  Today         42      [███████████████░]  ~58.4k tokens (95%)
-  Last 7 days   287     [██████████████░░]  ~312.4k tokens (90%)
-  All time      1.4k    [██████████████░░]  ~1.2M tokens (89%)
+  ════════════════════════════════════════════════════════════════════════
+
+  Total saved:  ~714.2M tokens  (94%)
+  Total calls:  14.3k
+  Efficiency:  ███████████████████████░  94%
+
+  By Period
+  ────────────────────────────────────────────────────────────────────────
+  Period             Calls           Saved  Ratio
+  ────────────────────────────────────────────────────────────────────────
+  Today                198    ~1.4M tokens  ███████████████████████░  95%
+  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
+  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%
+
+  By Call Type
+  ────────────────────────────────────────────────────────────────────────
+  #     Call type            Calls  Share
+  ────────────────────────────────────────────────────────────────────────
+  1.    search               14.1k  ████████████████    99%
+  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
+  ════════════════════════════════════════════════════════════════════════
 ```
 
+
 Savings are calculated as follows: for each call, semble records the total character count of the unique files containing returned chunks and the character count of the snippets returned. Estimated tokens saved is `(file chars − snippet chars) / 4` (4 chars per token). This is a conservative estimate: the baseline is reading matched files in full, which is how coding agents often explore unfamiliar code.
 
-By default, stats are stored in the OS cache folder (`~/Library/Caches/semble/` on macOS, `~/.cache/semble/` on Linux, `%LOCALAPPDATA%\semble\Cache\` on Windows). To override this location you can supply an environment variable `SEMBLE_CACHE_LOCATION` which should be the full path to the target cache location e.g. 'd:\caches\storemysemblecachehere'.
+</details>
+
+<details>
+<summary>Storage</summary>
+
+By default, your Semble savings statistics and any saved indexes are stored in the OS cache folder (`~/Library/Caches/semble/` on macOS, `~/.cache/semble/` on Linux, `%LOCALAPPDATA%\semble\Cache\` on Windows). To override this location you can supply an environment variable `SEMBLE_CACHE_LOCATION` which should be the full path to the target cache location e.g. `~/my-folder/my-caches/semble`.
 
 </details>
 

{semble-0.3.2 → semble-0.3.4}/README.md

@@ -24,7 +24,7 @@
 
 </div>
 
-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](#mcp-server) or call it from the shell via [AGENTS.md](#agentsmd) 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
 
@@ -120,23 +120,43 @@ Semble also always skips a set of well-known non-source directories regardless o
 `semble savings` shows how many tokens semble has saved across all your searches:
 
 ```bash
-semble savings           # summary by period
-semble savings --verbose # also show breakdown by call type
+semble savings
 ```
 
 ```
   Semble Token Savings
-  ════════════════════════════════════════════════════════════════
-  Period        Calls   Savings
-  ────────────────────────────────────────────────────────────────
-  Today         42      [███████████████░]  ~58.4k tokens (95%)
-  Last 7 days   287     [██████████████░░]  ~312.4k tokens (90%)
-  All time      1.4k    [██████████████░░]  ~1.2M tokens (89%)
+  ════════════════════════════════════════════════════════════════════════
+
+  Total saved:  ~714.2M tokens  (94%)
+  Total calls:  14.3k
+  Efficiency:  ███████████████████████░  94%
+
+  By Period
+  ────────────────────────────────────────────────────────────────────────
+  Period             Calls           Saved  Ratio
+  ────────────────────────────────────────────────────────────────────────
+  Today                198    ~1.4M tokens  ███████████████████████░  95%
+  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
+  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%
+
+  By Call Type
+  ────────────────────────────────────────────────────────────────────────
+  #     Call type            Calls  Share
+  ────────────────────────────────────────────────────────────────────────
+  1.    search               14.1k  ████████████████    99%
+  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
+  ════════════════════════════════════════════════════════════════════════
 ```
 
+
 Savings are calculated as follows: for each call, semble records the total character count of the unique files containing returned chunks and the character count of the snippets returned. Estimated tokens saved is `(file chars − snippet chars) / 4` (4 chars per token). This is a conservative estimate: the baseline is reading matched files in full, which is how coding agents often explore unfamiliar code.
 
-By default, stats are stored in the OS cache folder (`~/Library/Caches/semble/` on macOS, `~/.cache/semble/` on Linux, `%LOCALAPPDATA%\semble\Cache\` on Windows). To override this location you can supply an environment variable `SEMBLE_CACHE_LOCATION` which should be the full path to the target cache location e.g. 'd:\caches\storemysemblecachehere'.
+</details>
+
+<details>
+<summary>Storage</summary>
+
+By default, your Semble savings statistics and any saved indexes are stored in the OS cache folder (`~/Library/Caches/semble/` on macOS, `~/.cache/semble/` on Linux, `%LOCALAPPDATA%\semble\Cache\` on Windows). To override this location you can supply an environment variable `SEMBLE_CACHE_LOCATION` which should be the full path to the target cache location e.g. `~/my-folder/my-caches/semble`.
 
 </details>
 

{semble-0.3.2 → semble-0.3.4}/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, Pi, Command Code, and Antigravity.
+
+> **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,90 @@ Add to `~/.config/zed/settings.json` (or `.zed/settings.json` in your project):
 
 </details>
 
+<details>
+<summary>Reasonix</summary>
+
+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"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Pi</summary>
+
+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"]
+ }
+ }
+}
+```
+
+</details>
+
+<details>
+<summary>Antigravity</summary>
+
+Add to `~/.gemini/config/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "semble": {
+      "command": "uvx",
+      "args": ["--from", "semble[mcp]", "semble"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Command Code</summary>
+
+Add to `~/.commandcode/mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "semble": {
+ "command": "uvx",
+ "args": ["--from", "semble[mcp]", "semble"]
+ }
+ }
+}
+```
+
+Or use the CLI:
+
+```bash
+cmd mcp add --scope user semble -- uvx --from "semble[mcp]" semble
+```
+
+</details>
+
 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 +336,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, Command Code, Antigravity), 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 +348,7 @@ 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` |
+| Command Code | `commandcode.md` | `~/.commandcode/agents/semble-search.md` |
+| Antigravity | `antigravity.md` | `~/.gemini/config/skills/semble-search/SKILL.md` |

semble-0.3.4/src/semble/agents/commandcode.md

@@ -0,0 +1,41 @@
+---
+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.
+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 grep only when you need exhaustive literal matches or quick confirmation of an exact string.

semble-0.3.4/src/semble/agents/gemini.md

@@ -0,0 +1,43 @@
+---
+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 run_shell_command/read_file for any semantic or exploratory question.
+tools:
+  - run_shell_command
+  - 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 grep only when you need exhaustive literal matches or quick confirmation of an exact string.

semble-0.3.4/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.

semble-0.3.4/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.

{semble-0.3.2 → semble-0.3.4}/src/semble/cache.py

@@ -1,5 +1,6 @@
 import hashlib
 import json
+import logging
 import os
 import shutil
 import sys
@@ -13,6 +14,8 @@ from semble.index.types import PersistencePath
 from semble.types import ContentType
 from semble.utils import is_git_url, resolve_model_name
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from semble.index import SembleIndex
 
@@ -48,11 +51,24 @@ def _linux_cache_dir(name: str) -> Path:
     return base / name
 
 
+def _get_valid_user_cache_dir() -> Path | None:
+    """Gets the user cache dir if it is set and is a valid path."""
+    user_cache_location = os.getenv("SEMBLE_CACHE_LOCATION")
+    if user_cache_location is None:
+        return None
+    user_cache_dir = Path(user_cache_location)
+    if not user_cache_dir.is_absolute():
+        logger.warning("SEMBLE_CACHE_LOCATION is not an absolute path: %s", user_cache_location)
+        return None
+
+    return user_cache_dir
+
+
 def resolve_cache_folder() -> Path:
     """Resolves a cache folder, respects SEMBLE_CACHE_LOCATION (highest precedence), XDG_CACHE_HOME."""
     name = "semble"
-    if semble_cache_location := os.getenv("SEMBLE_CACHE_LOCATION"):
-        cache_dir = Path(semble_cache_location)
+    if user_cache_dir := _get_valid_user_cache_dir():
+        cache_dir = user_cache_dir
     elif sys.platform == "win32":
         cache_dir = _windows_cache_dir(name)
     elif sys.platform == "darwin":

{semble-0.3.2 → semble-0.3.4}/src/semble/cli.py

@@ -1,19 +1,26 @@
 import argparse
 import asyncio
 import json
+import re
 import sys
 import warnings
 from importlib.util import find_spec
+from shutil import rmtree
+from typing import Literal
 
 from model2vec.utils import get_package_extras
 
-from semble.cache import find_index_from_cache_folder
+from semble.cache import find_index_from_cache_folder, resolve_cache_folder
 from semble.index import SembleIndex
+from semble.index.types import PersistencePath
 from semble.stats import format_savings_report
 from semble.types import ContentType
 from semble.utils import format_results, is_git_url, resolve_chunk
 
-_CLI_DISPATCH_ARGS = frozenset({"search", "find-related", "install", "uninstall", "savings", "-h", "--help"})
+_CLI_DISPATCH_ARGS = frozenset({"search", "find-related", "install", "uninstall", "savings", "-h", "--help", "clear"})
+_CLEAR_CHOICE = Literal["all", "index", "savings"]
+
+_SHA_256_REGEX = re.compile(r"^[a-f0-9]{64}$")
 
 
 def _build_index(path: str, content: list[ContentType]) -> SembleIndex:
@@ -131,6 +138,35 @@ def _run_find_related(path: str, file_path: str, line: int, top_k: int, content:
     _maybe_save_index(index, path)
 
 
+def _run_clear(clear_type: _CLEAR_CHOICE) -> None:
+    """Run the `clear` subcommand."""
+    cache_folder = resolve_cache_folder()
+    if clear_type == "index" or clear_type == "all":
+        indexes = []
+        for path in cache_folder.glob("*/index"):
+            if not _SHA_256_REGEX.match(path.parent.name):
+                continue
+            if PersistencePath.from_path(path).non_existing():
+                continue
+            indexes.append(path)
+
+        if not indexes:
+            print(f"No indexes found to clear in `{cache_folder}`")
+        else:
+            for path in indexes:
+                index_folder = path.parent
+                rmtree(index_folder)
+                print(f"Cleared index at `{index_folder}`")
+
+    if clear_type == "savings" or clear_type == "all":
+        path = cache_folder / "savings.jsonl"
+        if not path.exists():
+            print(f"No savings file found at `{path}`")
+        else:
+            path.unlink()
+            print(f"Cleared savings at `{path}`")
+
+
 def _cli_main() -> None:
     parser = argparse.ArgumentParser(prog="semble")
     sub = parser.add_subparsers(dest="command")
@@ -141,6 +177,9 @@ def _cli_main() -> None:
     search_p.add_argument("-k", "--top-k", type=int, default=5, help="Number of results (default: 5).")
     _add_content_args(search_p)
 
+    clear_p = sub.add_parser("clear", help="Clear the index cache.")
+    clear_p.add_argument("type", choices=["all", "index", "savings"], help="Type of cache to clear.")
+
     related_p = sub.add_parser("find-related", help="Find code similar to a specific location.")
     related_p.add_argument("file_path", help="File path as shown in search results.")
     related_p.add_argument("line", type=int, help="Line number (1-indexed).")
@@ -148,8 +187,7 @@ def _cli_main() -> None:
     related_p.add_argument("-k", "--top-k", type=int, default=5, help="Number of results (default: 5).")
     _add_content_args(related_p)
 
-    savings_p = sub.add_parser("savings", help="Show token savings and usage stats.")
-    savings_p.add_argument("--verbose", action="store_true", help="Also show usage breakdown by call type.")
+    sub.add_parser("savings", help="Show token savings and usage stats.")
 
     sub.add_parser("install", help="Interactively configure semble across coding agents.")
     sub.add_parser("uninstall", help="Interactively remove semble configuration from coding agents.")
@@ -157,11 +195,13 @@ def _cli_main() -> None:
     args = parser.parse_args()
 
     if args.command == "savings":
-        print(format_savings_report(verbose=args.verbose))
+        print(format_savings_report())
     elif args.command in ("install", "uninstall"):
         from semble.installer import run
 
         run(args.command)
+    elif args.command == "clear":
+        _run_clear(args.type)
     elif args.command == "search":
         _run_search(args.path, args.query, args.top_k, _resolve_content(args.content, args.include_text_files))
     elif args.command == "find-related":