codebase-brain-mcp 0.2.0__tar.gz → 0.2.1__tar.gz

{codebase_brain_mcp-0.2.0 → codebase_brain_mcp-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-brain-mcp
-Version: 0.2.0
+Version: 0.2.1
 Summary: An MCP server that gives AI agents a cited, searchable memory of a codebase.
 Keywords: mcp,model-context-protocol,rag,code-search,ai-agents,claude,git
 Author: Noman Nazir
@@ -103,7 +103,7 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
 
 | Tool | What it does |
 |---|---|
-| `index_repo(source, name?)` | Index a local path or an `https://` git URL (shallow clone). Reports progress. |
+| `index_repo(source, name?)` | Index a local path or an `https://` git URL (blobless clone with full history). Reports progress. |
 | `ask_codebase(question, repo?, k?)` | The most relevant code and docs as cited sources, plus related commits, with instructions to answer only from them. |
 | `search(query, repo?, k?, path_prefix?, kinds?)` | Raw hybrid search, filterable by path and chunk kind. |
 | `explain_history(symbol? \| path, start_line?, end_line?, repo?)` | Every commit that changed a function or line range, newest first, with the relevant diff, current authorship, and PR titles and descriptions (GitHub). |
@@ -117,15 +117,67 @@ Also included: the resource `brain://repos`, and the prompt `answer_with_citatio
 
 ## Install
 
-Codebase Brain runs on your own machine, so there's no server or account, and it's free. With
-[uv](https://docs.astral.sh/uv/):
+Codebase Brain runs on your own machine, so there's no server or account, and it's free. It works with any
+MCP-compatible assistant. All you need is [uv](https://docs.astral.sh/uv/), and every client runs the same command:
+`uvx codebase-brain-mcp`.
+
+**Claude Code**
 
 ```bash
-# Claude Code
 claude mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+**Cursor:** `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project)
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
 
-# Any MCP client (Claude Desktop, Cursor, ...): add this server to its config
-{ "command": "uvx", "args": ["codebase-brain-mcp"] }
+**Claude Desktop:** Settings → Developer → Edit Config (`claude_desktop_config.json`), then restart the app
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**VS Code (GitHub Copilot agent mode):** `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "codebase-brain": { "type": "stdio", "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**Windsurf:** `~/.codeium/windsurf/mcp_config.json`. **Gemini CLI:** `~/.gemini/settings.json`. Both use the same
+`mcpServers` block as Cursor.
+
+**OpenAI Codex CLI**
+
+```bash
+codex mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+> **Tool doesn't start?** Desktop apps often don't see your shell's `PATH`. Run `which uvx` and put that full
+> path in `"command"`, for example `"/Users/you/.local/bin/uvx"`.
+
+Optional: install the [skill](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/skills/codebase-brain/SKILL.md).
+It tells the agent which tool fits which question, to cite every claim, to check history before removing odd code,
+and to run impact analysis before editing. For Claude Code, run the commands below. Other agents that read
+`SKILL.md` files take the same file in their own skills folder.
+
+```bash
+mkdir -p ~/.claude/skills/codebase-brain
+curl -fsSL https://raw.githubusercontent.com/Nomannazir/codebase-brain-mcp/main/skills/codebase-brain/SKILL.md \
+  -o ~/.claude/skills/codebase-brain/SKILL.md
 ```
 
 ## Quick start
@@ -154,7 +206,7 @@ src/itsdangerous/timed.py:72-158
   ...
 ```
 
-### Use it from Claude Code
+### Use a local checkout instead (for development)
 
 ```bash
 claude mcp add codebase-brain -- uv run --directory /path/to/codebase-brain-mcp codebase-brain
@@ -288,13 +340,14 @@ How it's measured:
 - **nDCG@10:** each target is credited once, so duplicate chunks don't inflate the score.
 - **Confidence intervals:** 95% bootstrap over questions, seeded.
 - **Relevance:** a result is relevant if it's in the target file and, when the target names a symbol, is that symbol
-  or one of its methods.
+  or one of its methods. A docs target can name a section (`FAQ > How do I stop retrying early?`), and then that
+  section or one of its subsections counts.
 - **Dataset rot:** the harness fails if a target no longer exists at the pinned commit.
 
 ## How it works
 
 ```
-source ─► resolve (local dir / shallow https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
+source ─► resolve (local dir / blobless https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
        ─► chunk (ast / tree-sitter / headings / windows) ─► embed (fastembed) ─► SQLite: chunks + vectors + FTS5
 query  ─► BM25 top 50 ┐
        ─► vector top 50 ┴─► reciprocal-rank fusion ─► filters ─► cited sources
@@ -314,7 +367,7 @@ query  ─► BM25 top 50 ┐
 ## Development
 
 ```bash
-uv run pytest           # 54 tests, offline (hash embedder, temporary git repos, in-process MCP client)
+uv run pytest           # 67 tests, offline (hash embedder, temporary git repos, in-process MCP client)
 uv run ruff check .     # lint
 uv run ruff format .    # format
 uv run pyright          # types

{codebase_brain_mcp-0.2.0 → codebase_brain_mcp-0.2.1}/README.md

@@ -74,7 +74,7 @@ A plug-in for any AI assistant that turns a codebase into something it can actua
 
 | Tool | What it does |
 |---|---|
-| `index_repo(source, name?)` | Index a local path or an `https://` git URL (shallow clone). Reports progress. |
+| `index_repo(source, name?)` | Index a local path or an `https://` git URL (blobless clone with full history). Reports progress. |
 | `ask_codebase(question, repo?, k?)` | The most relevant code and docs as cited sources, plus related commits, with instructions to answer only from them. |
 | `search(query, repo?, k?, path_prefix?, kinds?)` | Raw hybrid search, filterable by path and chunk kind. |
 | `explain_history(symbol? \| path, start_line?, end_line?, repo?)` | Every commit that changed a function or line range, newest first, with the relevant diff, current authorship, and PR titles and descriptions (GitHub). |
@@ -88,15 +88,67 @@ Also included: the resource `brain://repos`, and the prompt `answer_with_citatio
 
 ## Install
 
-Codebase Brain runs on your own machine, so there's no server or account, and it's free. With
-[uv](https://docs.astral.sh/uv/):
+Codebase Brain runs on your own machine, so there's no server or account, and it's free. It works with any
+MCP-compatible assistant. All you need is [uv](https://docs.astral.sh/uv/), and every client runs the same command:
+`uvx codebase-brain-mcp`.
+
+**Claude Code**
 
 ```bash
-# Claude Code
 claude mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+**Cursor:** `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project)
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
 
-# Any MCP client (Claude Desktop, Cursor, ...): add this server to its config
-{ "command": "uvx", "args": ["codebase-brain-mcp"] }
+**Claude Desktop:** Settings → Developer → Edit Config (`claude_desktop_config.json`), then restart the app
+
+```json
+{
+  "mcpServers": {
+    "codebase-brain": { "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**VS Code (GitHub Copilot agent mode):** `.vscode/mcp.json`
+
+```json
+{
+  "servers": {
+    "codebase-brain": { "type": "stdio", "command": "uvx", "args": ["codebase-brain-mcp"] }
+  }
+}
+```
+
+**Windsurf:** `~/.codeium/windsurf/mcp_config.json`. **Gemini CLI:** `~/.gemini/settings.json`. Both use the same
+`mcpServers` block as Cursor.
+
+**OpenAI Codex CLI**
+
+```bash
+codex mcp add codebase-brain -- uvx codebase-brain-mcp
+```
+
+> **Tool doesn't start?** Desktop apps often don't see your shell's `PATH`. Run `which uvx` and put that full
+> path in `"command"`, for example `"/Users/you/.local/bin/uvx"`.
+
+Optional: install the [skill](https://github.com/Nomannazir/codebase-brain-mcp/blob/main/skills/codebase-brain/SKILL.md).
+It tells the agent which tool fits which question, to cite every claim, to check history before removing odd code,
+and to run impact analysis before editing. For Claude Code, run the commands below. Other agents that read
+`SKILL.md` files take the same file in their own skills folder.
+
+```bash
+mkdir -p ~/.claude/skills/codebase-brain
+curl -fsSL https://raw.githubusercontent.com/Nomannazir/codebase-brain-mcp/main/skills/codebase-brain/SKILL.md \
+  -o ~/.claude/skills/codebase-brain/SKILL.md
 ```
 
 ## Quick start
@@ -125,7 +177,7 @@ src/itsdangerous/timed.py:72-158
   ...
 ```
 
-### Use it from Claude Code
+### Use a local checkout instead (for development)
 
 ```bash
 claude mcp add codebase-brain -- uv run --directory /path/to/codebase-brain-mcp codebase-brain
@@ -259,13 +311,14 @@ How it's measured:
 - **nDCG@10:** each target is credited once, so duplicate chunks don't inflate the score.
 - **Confidence intervals:** 95% bootstrap over questions, seeded.
 - **Relevance:** a result is relevant if it's in the target file and, when the target names a symbol, is that symbol
-  or one of its methods.
+  or one of its methods. A docs target can name a section (`FAQ > How do I stop retrying early?`), and then that
+  section or one of its subsections counts.
 - **Dataset rot:** the harness fails if a target no longer exists at the pinned commit.
 
 ## How it works
 
 ```
-source ─► resolve (local dir / shallow https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
+source ─► resolve (local dir / blobless https clone) ─► list files (.gitignore-aware, skips binaries and lockfiles)
        ─► chunk (ast / tree-sitter / headings / windows) ─► embed (fastembed) ─► SQLite: chunks + vectors + FTS5
 query  ─► BM25 top 50 ┐
        ─► vector top 50 ┴─► reciprocal-rank fusion ─► filters ─► cited sources
@@ -285,7 +338,7 @@ query  ─► BM25 top 50 ┐
 ## Development
 
 ```bash
-uv run pytest           # 54 tests, offline (hash embedder, temporary git repos, in-process MCP client)
+uv run pytest           # 67 tests, offline (hash embedder, temporary git repos, in-process MCP client)
 uv run ruff check .     # lint
 uv run ruff format .    # format
 uv run pyright          # types

{codebase_brain_mcp-0.2.0 → codebase_brain_mcp-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codebase-brain-mcp"
-version = "0.2.0"
+version = "0.2.1"
 description = "An MCP server that gives AI agents a cited, searchable memory of a codebase."
 readme = "README.md"
 license = "MIT"

{codebase_brain_mcp-0.2.0 → codebase_brain_mcp-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "codebase-brain-mcp"
-version = "0.2.0"
+version = "0.2.1"
 description = "An MCP server that gives AI agents a cited, searchable memory of a codebase."
 readme = "README.md"
 authors = [

{codebase_brain_mcp-0.2.0 → codebase_brain_mcp-0.2.1}/src/codebase_brain_mcp/server.py

@@ -2,6 +2,10 @@
 
 from __future__ import annotations
 
+import inspect
+from collections.abc import Callable
+from typing import Annotated, Any
+
 import anyio
 import anyio.from_thread
 import anyio.to_thread
@@ -29,6 +33,16 @@ READ_ONLY = ToolAnnotations(read_only_hint=True, open_world_hint=False)
 MAX_RESULTS = 25
 SNIPPET_CHARS = 1_800
 
+# Parameters shared by several tools, described once so every tool explains them the same way.
+Repo = Annotated[
+    str | None,
+    Field(description="Name of an indexed repo, as list_repos shows it. Leave out when only one repo is indexed."),
+]
+ResultCount = Annotated[int, Field(description=f"How many results to return, 1 to {MAX_RESULTS}.")]
+PathPrefix = Annotated[
+    str | None, Field(description='Only consider files under this path, e.g. "src/auth/" or "docs/".')
+]
+
 
 class IndexResult(BaseModel):
     repo: str
@@ -164,14 +178,23 @@ def build_server(brain: Brain | None = None) -> MCPServer:
     brain = brain or Brain(load_settings())
     server = MCPServer("codebase-brain", instructions=INSTRUCTIONS, version=__version__)
 
-    @server.tool(
-        annotations=ToolAnnotations(
-            read_only_hint=False, destructive_hint=False, idempotent_hint=True, open_world_hint=True
-        )
+    @_tool(
+        server,
+        ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=True, open_world_hint=True),
     )
-    async def index_repo(source: str, ctx: Context, name: str | None = None) -> IndexResult:
-        """Index a repository so it can be searched. `source` is a local directory or an https git URL
-        (cloned shallowly). Re-running only re-embeds files that changed since the last run."""
+    async def index_repo(
+        source: Annotated[
+            str, Field(description="A local directory, or an https git URL such as https://github.com/owner/repo.")
+        ],
+        ctx: Context,
+        name: Annotated[
+            str | None, Field(description="Name to index it under. Defaults to the folder or repository name.")
+        ] = None,
+    ) -> IndexResult:
+        """Index a repository so the other tools can search it. Use this first, and again after the code
+        changes: re-running only re-embeds files whose content changed. A URL is cloned with full history
+        (blobless), so explain_history works. Reports progress while it runs, and returns file counts and
+        the commit indexed."""
 
         def progress(done: int, total: int, message: str) -> None:
             anyio.from_thread.run(ctx.report_progress, done, total, message)
@@ -182,19 +205,37 @@ def build_server(brain: Brain | None = None) -> MCPServer:
             raise ToolError(str(exc)) from exc
         return IndexResult(**report.__dict__)
 
-    @server.tool(annotations=READ_ONLY)
+    @_tool(server, READ_ONLY)
     async def search(
-        query: str, repo: str | None = None, k: int = 8, path_prefix: str | None = None, kinds: list[str] | None = None
+        query: Annotated[str, Field(description="An identifier (normalizeRetryOptions) or plain words.")],
+        repo: Repo = None,
+        k: ResultCount = 8,
+        path_prefix: PathPrefix = None,
+        kinds: Annotated[
+            list[str] | None,
+            Field(
+                description="Only these chunk kinds: function, class, method, interface, type, enum, "
+                "module, section (docs) or code (other files)."
+            ),
+        ] = None,
     ) -> SearchResult:
-        """Hybrid search (BM25 keywords + embeddings, fused by rank). Filter by `path_prefix`
-        (e.g. "src/auth/") or `kinds` (function, class, method, interface, type, enum, module, section, code)."""
+        """Hybrid search over code and docs (BM25 keywords plus local embeddings, fused by rank). Use this
+        for a targeted lookup, or when you need filters by folder or chunk kind; for a question you'll answer
+        in prose, use ask_codebase instead. Returns ranked chunks, each with a path:start-end citation,
+        its symbol and a snippet."""
         hits = await _search(brain, query, repo, k, path_prefix, kinds)
         return SearchResult(repo=brain.resolve_repo(repo), query=query, results=[_source(h) for h in hits])
 
-    @server.tool(annotations=READ_ONLY)
-    async def ask_codebase(question: str, repo: str | None = None, k: int = 8) -> AskResult:
-        """Gather the code and docs most relevant to a question, as numbered, cited sources.
-        Answer from these sources only, citing each claim as path:start-end."""
+    @_tool(server, READ_ONLY)
+    async def ask_codebase(
+        question: Annotated[str, Field(description='A question in plain words, e.g. "How are sessions expired?"')],
+        repo: Repo = None,
+        k: ResultCount = 8,
+    ) -> AskResult:
+        """Gather the code and docs most relevant to a question, plus related commits, as numbered,
+        cited sources. Use this to answer "how does X work?" or "where is Y handled?" questions. Answer
+        from these sources only and cite each claim as path:start-end; open a source in full with
+        read_lines. For filters, use search."""
         hits = await _search(brain, question, repo, k, None, None)
         commits = await _call(lambda: brain.search_history(question, repo, 3))
         instructions = (
@@ -212,57 +253,95 @@ def build_server(brain: Brain | None = None) -> MCPServer:
             related_commits=[_commit(c) for c in commits],
         )
 
-    @server.tool(annotations=ToolAnnotations(read_only_hint=True, open_world_hint=True))
+    @_tool(server, ToolAnnotations(read_only_hint=True, open_world_hint=True))
     async def explain_history(
-        repo: str | None = None,
-        symbol: str | None = None,
-        path: str | None = None,
-        start_line: int | None = None,
-        end_line: int | None = None,
-        max_commits: int = 8,
+        repo: Repo = None,
+        symbol: Annotated[
+            str | None,
+            Field(description='A function, class or method, e.g. "unsign" or "Signer.sign". Use this or path.'),
+        ] = None,
+        path: Annotated[
+            str | None, Field(description="A file in the repo. Narrow it with start_line and end_line.")
+        ] = None,
+        start_line: Annotated[int | None, Field(description="First line of the range (with path).")] = None,
+        end_line: Annotated[int | None, Field(description="Last line of the range (with path).")] = None,
+        max_commits: Annotated[int, Field(description="How many commits to return, newest first.")] = 8,
     ) -> HistoryResult:
-        """Why code looks the way it does. Give a `symbol` (e.g. "unsign" or "Signer.sign"), or a `path`
-        with optional line range. Returns who wrote the current lines, every commit that changed them
-        (with the relevant diff), and the pull requests behind those commits."""
+        """Why code looks the way it does. Use this before removing or rewriting code that looks odd, or
+        to answer "why is it like this?". Give a symbol, or a path with an optional line range. Returns
+        who wrote the current lines, every commit that changed them (with the relevant diff), and the
+        title and description of the pull request behind each commit (GitHub only)."""
         report = await _call(lambda: brain.explain_history(repo, path, symbol, start_line, end_line, max_commits))
         return _history(report)
 
-    @server.tool(annotations=READ_ONLY)
+    @_tool(server, READ_ONLY)
     async def impact_of_change(
-        symbol: str, repo: str | None = None, path: str | None = None, depth: int = 2
+        symbol: Annotated[
+            str, Field(description='The function, class or method you plan to change, e.g. "discount" or "Cart.total".')
+        ],
+        repo: Repo = None,
+        path: Annotated[
+            str | None, Field(description="The file that defines symbol, when several files define that name.")
+        ] = None,
+        depth: Annotated[
+            int, Field(description="1 = direct users only; 2 or 3 also follows users of those users.")
+        ] = 2,
     ) -> ImpactResult:
-        """What breaks if `symbol` changes: code that uses it directly, code that uses that code
-        (up to `depth`, max 3), and the tests involved. Python, JavaScript and TypeScript are analysed structurally."""
+        """What breaks if a symbol changes: code that uses it directly, code that uses that code, and the
+        tests involved. Use this before editing a shared function, and run or update the tests it lists.
+        Python, JavaScript and TypeScript are analysed structurally. Matches are by name, so check the
+        same-name notes it returns."""
         report = await _call(lambda: brain.impact_of_change(repo, symbol, path, depth))
         return _impact(report)
 
-    @server.tool(annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False))
+    @_tool(server, ToolAnnotations(read_only_hint=True, open_world_hint=False))
     async def find_doc_drift(
-        repo: str | None = None, path_prefix: str | None = None, check_history: bool = True, limit: int = 50
+        repo: Repo = None,
+        path_prefix: PathPrefix = None,
+        check_history: Annotated[
+            bool, Field(description="Also flag doc sections last edited long before the code they describe.")
+        ] = True,
+        limit: Annotated[int, Field(description="Most findings to return, 1 to 200, most severe first.")] = 50,
     ) -> DriftResult:
-        """Documentation that no longer matches the code: files, functions, settings and flags that don't
-        exist; examples passing parameters a function doesn't take; imports that would fail; and docs last
-        edited long before the code they describe changed. Each finding cites the doc section."""
+        """Documentation that no longer matches the code. Use this to check a README or docs folder, or
+        before a release. Finds files, functions, settings and flags that don't exist; code examples that
+        pass parameters a function doesn't take; imports that would fail; and stale sections. Each finding
+        has a severity, cites the doc section and suggests a fix. Changelogs are skipped."""
         report = await _call(lambda: brain.find_doc_drift(repo, path_prefix, check_history, max(1, min(limit, 200))))
         return _drift(brain.resolve_repo(repo), report)
 
-    @server.tool(annotations=READ_ONLY)
-    async def search_history(query: str, repo: str | None = None, k: int = 5) -> list[CommitInfo]:
-        """Find commits by what their messages say, e.g. "fix timezone" or "drop python 3.8"."""
+    @_tool(server, READ_ONLY)
+    async def search_history(
+        query: Annotated[
+            str, Field(description='Words from commit messages, e.g. "fix timezone" or "drop python 3.8".')
+        ],
+        repo: Repo = None,
+        k: ResultCount = 5,
+    ) -> list[CommitInfo]:
+        """Find commits by what their messages say. Use this to answer "when did we change X?" or "which
+        commit fixed Y?". For the history of one function or file, use explain_history instead."""
         commits = await _call(lambda: brain.search_history(query, repo, max(1, min(k, MAX_RESULTS))))
         return [_commit(c) for c in commits]
 
-    @server.tool(annotations=READ_ONLY)
-    async def read_lines(path: str, start: int, end: int, repo: str | None = None) -> str:
-        """Exact, numbered lines from a file in an indexed repo, e.g. to open a citation in full."""
+    @_tool(server, READ_ONLY)
+    async def read_lines(
+        path: Annotated[str, Field(description="The file, relative to the repo root, as a citation shows it.")],
+        start: Annotated[int, Field(description="First line to return (1-based).")],
+        end: Annotated[int, Field(description="Last line to return (inclusive).")],
+        repo: Repo = None,
+    ) -> str:
+        """Exact, numbered lines from a file in an indexed repo. Use this to open a citation in full
+        before quoting or editing it, since search results are trimmed snippets. Refuses paths outside
+        the repo."""
         try:
             return brain.read_lines(repo, path, start, end)
         except BrainError as exc:
             raise ToolError(str(exc)) from exc
 
-    @server.tool(annotations=READ_ONLY)
+    @_tool(server, READ_ONLY)
     async def list_repos() -> list[RepoSummary]:
-        """Repositories indexed so far, with size, languages and the commit they were indexed at."""
+        """Repositories indexed so far, with their size, languages and the commit they were indexed at.
+        Use this first to see what's available and to get the repo names the other tools take."""
         return [_summary(info) for info in brain.repos()]
 
     @server.resource(
@@ -288,6 +367,15 @@ def build_server(brain: Brain | None = None) -> MCPServer:
     return server
 
 
+def _tool(server: MCPServer, annotations: ToolAnnotations) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Register a tool with its docstring, dedented: clients show descriptions as they are sent."""
+
+    def register(fn: Callable[..., Any]) -> Callable[..., Any]:
+        return server.tool(annotations=annotations, description=inspect.cleandoc(fn.__doc__ or ""))(fn)
+
+    return register
+
+
 async def _search(
     brain: Brain, query: str, repo: str | None, k: int, path_prefix: str | None, kinds: list[str] | None
 ) -> list[Hit]:

{codebase_brain_mcp-0.2.0 → codebase_brain_mcp-0.2.1}/src/codebase_brain_mcp/sources.py

@@ -97,7 +97,7 @@ def default_name(source: str) -> str:
 
 
 def resolve(source: str, clone_dir: Path) -> Path:
-    """The repository's root on disk. URLs are shallow-cloned (or refreshed) under ``clone_dir``."""
+    """The repository's root on disk. URLs are cloned blobless (or refreshed) under ``clone_dir``."""
     if not is_url(source):
         root = Path(source).expanduser().resolve()
         if not root.is_dir():