coderag-ai 0.3.4__tar.gz → 0.4.0__tar.gz

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderag-ai
-Version: 0.3.4
+Version: 0.4.0
 Summary: Token-efficient, structure-aware Code Intelligence + RAG for private source repositories.
 Project-URL: Homepage, https://github.com/galacticsurfer/coderag
 Project-URL: Repository, https://github.com/galacticsurfer/coderag
@@ -109,15 +109,21 @@ Full details: [`docs/architecture.md`](docs/architecture.md), plus ADRs in
 
 ## Install
 
-**macOS / no Docker (easiest):** ships a rootless bundled PostgreSQL+pgvector — no Docker,
-Homebrew, or `sudo`:
+**Two commands.** Ships a rootless bundled PostgreSQL+pgvector — no Docker, Homebrew, or `sudo`:
 
 ```bash
 pipx install "coderag-ai[mcp,localdb]"
-coderag localdb start            # starts Postgres + applies migrations, prints the URL
-export CODERAG_DATABASE_URL='…'  # the URL it prints
-coderag index /path/to/your-project --name myproject
-coderag search "where is authentication handled?"
+cd /path/to/your-project && coderag setup
+```
+
+`coderag setup` starts the database, applies migrations, indexes the repo, registers the MCP
+server with Claude Code, and appends the retrieval nudge to your `CLAUDE.md` — the step that
+makes Claude Code actually call the tools. It records the database URL, so **no
+`export CODERAG_DATABASE_URL` is needed**; later commands find it automatically. Re-running is
+safe (it won't duplicate the nudge). Opt out with `--no-mcp` / `--no-claude-md`.
+
+```bash
+coderag search "where is authentication handled?"   # works in any new shell
 ```
 
 Full walkthrough incl. Claude Code wiring: [`docs/install-macos.md`](docs/install-macos.md).
@@ -345,7 +351,39 @@ claude mcp add coderag \
 Tools: `coderag_context`, `coderag_search`, `coderag_symbol`, `coderag_repositories`,
 `coderag_index`. Every call is recorded, so `/dashboard` shows the savings live. No API key
 needed — Claude Code is the LLM. **Full step-by-step:**
-[`docs/claude-code.md`](docs/claude-code.md).
+[`docs/claude-code.md`](docs/claude-code.md). Copy-pasteable `.mcp.json` + `CLAUDE.md` snippet,
+with **real** captured tool output: [`examples/mcp/`](examples/mcp/).
+
+## Composes with other token-efficiency tools
+
+CodeRAG attacks **one slice** of token spend: the code you'd otherwise read whole files to get.
+It does nothing about output tokens, conversation history, cache placement, or model routing.
+Tools that target those slices stack with it, because the slices are disjoint:
+
+| Slice | Billed at | CodeRAG | Tools like [Caveman](https://caveman.so) |
+|---|---|:--:|:--:|
+| File-reading input | 1× input | ✅ retrieval instead of whole files | — |
+| Output tokens | **5× input** | ❌ | ✅ output compression |
+| Conversation history | ~0.1× (cached) | ❌ | ✅ context compression |
+| Cache placement | — | ❌ | ✅ automatic breakpoints |
+| Model routing | varies | ❌ | ✅ cheapest model passing evals |
+
+Savings on disjoint slices are near-additive. On a typical mid-session turn, CodeRAG's measured
+file-slice reduction works out to ~26% of cost; adding an output-compression layer takes the
+combined figure to roughly ~38%. **Both halves of that are models, not measurements** — verify
+on your own workload before believing either.
+
+**Wiring:** they use different mechanisms and don't conflict — CodeRAG is an MCP server, a
+compression skill is a Skill, a proxy is an `ANTHROPIC_BASE_URL`. CodeRAG's own `ask` can also
+route through such a proxy, since the LLM base URL is configurable:
+
+```bash
+export CODERAG_ANTHROPIC_BASE_URL=http://localhost:<proxy-port>
+```
+
+Enable one at a time and compare `/cost` between them — a proxy that compresses context may be
+compressing context CodeRAG already minimised, so the marginal gain can be smaller than the two
+vendors' claims added together.
 
 ## Editor integration (VS Code)
 

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/README.md

@@ -48,15 +48,21 @@ Full details: [`docs/architecture.md`](docs/architecture.md), plus ADRs in
 
 ## Install
 
-**macOS / no Docker (easiest):** ships a rootless bundled PostgreSQL+pgvector — no Docker,
-Homebrew, or `sudo`:
+**Two commands.** Ships a rootless bundled PostgreSQL+pgvector — no Docker, Homebrew, or `sudo`:
 
 ```bash
 pipx install "coderag-ai[mcp,localdb]"
-coderag localdb start            # starts Postgres + applies migrations, prints the URL
-export CODERAG_DATABASE_URL='…'  # the URL it prints
-coderag index /path/to/your-project --name myproject
-coderag search "where is authentication handled?"
+cd /path/to/your-project && coderag setup
+```
+
+`coderag setup` starts the database, applies migrations, indexes the repo, registers the MCP
+server with Claude Code, and appends the retrieval nudge to your `CLAUDE.md` — the step that
+makes Claude Code actually call the tools. It records the database URL, so **no
+`export CODERAG_DATABASE_URL` is needed**; later commands find it automatically. Re-running is
+safe (it won't duplicate the nudge). Opt out with `--no-mcp` / `--no-claude-md`.
+
+```bash
+coderag search "where is authentication handled?"   # works in any new shell
 ```
 
 Full walkthrough incl. Claude Code wiring: [`docs/install-macos.md`](docs/install-macos.md).
@@ -284,7 +290,39 @@ claude mcp add coderag \
 Tools: `coderag_context`, `coderag_search`, `coderag_symbol`, `coderag_repositories`,
 `coderag_index`. Every call is recorded, so `/dashboard` shows the savings live. No API key
 needed — Claude Code is the LLM. **Full step-by-step:**
-[`docs/claude-code.md`](docs/claude-code.md).
+[`docs/claude-code.md`](docs/claude-code.md). Copy-pasteable `.mcp.json` + `CLAUDE.md` snippet,
+with **real** captured tool output: [`examples/mcp/`](examples/mcp/).
+
+## Composes with other token-efficiency tools
+
+CodeRAG attacks **one slice** of token spend: the code you'd otherwise read whole files to get.
+It does nothing about output tokens, conversation history, cache placement, or model routing.
+Tools that target those slices stack with it, because the slices are disjoint:
+
+| Slice | Billed at | CodeRAG | Tools like [Caveman](https://caveman.so) |
+|---|---|:--:|:--:|
+| File-reading input | 1× input | ✅ retrieval instead of whole files | — |
+| Output tokens | **5× input** | ❌ | ✅ output compression |
+| Conversation history | ~0.1× (cached) | ❌ | ✅ context compression |
+| Cache placement | — | ❌ | ✅ automatic breakpoints |
+| Model routing | varies | ❌ | ✅ cheapest model passing evals |
+
+Savings on disjoint slices are near-additive. On a typical mid-session turn, CodeRAG's measured
+file-slice reduction works out to ~26% of cost; adding an output-compression layer takes the
+combined figure to roughly ~38%. **Both halves of that are models, not measurements** — verify
+on your own workload before believing either.
+
+**Wiring:** they use different mechanisms and don't conflict — CodeRAG is an MCP server, a
+compression skill is a Skill, a proxy is an `ANTHROPIC_BASE_URL`. CodeRAG's own `ask` can also
+route through such a proxy, since the LLM base URL is configurable:
+
+```bash
+export CODERAG_ANTHROPIC_BASE_URL=http://localhost:<proxy-port>
+```
+
+Enable one at a time and compare `/cost` between them — a proxy that compresses context may be
+compressing context CodeRAG already minimised, so the marginal gain can be smaller than the two
+vendors' claims added together.
 
 ## Editor integration (VS Code)
 

coderag_ai-0.4.0/examples/mcp/.mcp.json

@@ -0,0 +1,23 @@
+{
+  "$comment": [
+    "Copy this file to the ROOT of the project you want Claude Code to search,",
+    "rename it to '.mcp.json', and edit the two values below.",
+    "  command  -> absolute path to coderag-mcp ('which coderag-mcp').",
+    "              An absolute path matters: Claude Code spawns the process",
+    "              without your shell's PATH.",
+    "  CODERAG_DATABASE_URL -> the URL 'coderag localdb start' printed",
+    "                          ('echo $CODERAG_DATABASE_URL'). JSON has no shell",
+    "                          expansion, so paste the literal value.",
+    "  CODERAG_DEFAULT_REPOSITORY -> the --name you indexed with.",
+    "Then reload VS Code / restart Claude Code and run /mcp to confirm."
+  ],
+  "mcpServers": {
+    "coderag": {
+      "command": "/Users/you/.local/bin/coderag-mcp",
+      "env": {
+        "CODERAG_DATABASE_URL": "postgresql+psycopg://postgres:@/postgres?host=/Users/you/.coderag/pgdata",
+        "CODERAG_DEFAULT_REPOSITORY": "myproject"
+      }
+    }
+  }
+}

coderag_ai-0.4.0/examples/mcp/CLAUDE.md

@@ -0,0 +1,23 @@
+# Append this to your project's CLAUDE.md
+
+Registering the MCP server is not enough on its own — Claude Code will keep
+globbing, grepping, and reading whole files unless you tell it not to. This
+snippet is what actually produces the token saving.
+
+---
+
+## Code search
+
+This repo is indexed in CodeRAG. To find or understand code, call the
+`coderag_context` or `coderag_search` MCP tools **before** globbing/grepping or
+reading whole files — they return only the relevant symbols and cost far fewer
+input tokens.
+
+- `coderag_search` — locate symbols ("where is X defined?"). Returns ranked
+  symbols with file, line range, and why each matched.
+- `coderag_context` — understand behaviour ("why does X happen?"). Returns the
+  target symbol plus its dependencies, callers, and tests, under a token budget.
+- `coderag_symbol` — fetch one symbol's full source by qualified name.
+
+Read whole files only when the retrieved context is genuinely insufficient. If
+the index looks stale, call `coderag_index` with `incremental: true`.

coderag_ai-0.4.0/examples/mcp/README.md

@@ -0,0 +1,152 @@
+# MCP setup example (Claude Code)
+
+A complete, copy-pasteable setup, plus **real** tool output captured from the
+bundled demo repository — not illustrative JSON.
+
+Files here:
+
+| File | Use |
+|---|---|
+| [`.mcp.json`](.mcp.json) | Drop in your project root (project-scoped server, committable) |
+| [`CLAUDE.md`](CLAUDE.md) | Append to your project's `CLAUDE.md` — **this is what makes Claude Code actually use the tools** |
+
+---
+
+## 1. Install and start the database
+
+```bash
+pipx install "coderag-ai[mcp,localdb]"
+coderag localdb start            # prints the DB URL; applies migrations
+export CODERAG_DATABASE_URL='…'  # paste what it printed; add to ~/.zshrc
+```
+
+## 2. Index the repo you want to search
+
+```bash
+cd /path/to/your-project
+coderag index . --name myproject
+coderag search "where is authentication handled?"   # sanity check, no LLM needed
+```
+
+## 3. Register the server — pick one
+
+**A. One command, all projects:**
+
+```bash
+claude mcp add coderag \
+  -e CODERAG_DATABASE_URL="$CODERAG_DATABASE_URL" \
+  -e CODERAG_DEFAULT_REPOSITORY=myproject \
+  -s user \
+  -- "$(which coderag-mcp)"
+```
+
+**B. Committed `.mcp.json`** (see the file in this directory) so your team gets it
+automatically. Note JSON has no shell expansion — paste literal values.
+
+Either way: use the **absolute path** to `coderag-mcp`. Claude Code spawns it
+without your shell's PATH, so a bare command name fails with "command not found".
+
+## 4. Add the `CLAUDE.md` nudge
+
+Append [`CLAUDE.md`](CLAUDE.md) to your project's `CLAUDE.md`. **Without it the
+saving is zero** — the tools are registered but unused.
+
+## 5. Verify
+
+Run `/mcp` in Claude Code. You should see `coderag` **connected** with five tools.
+Then just ask a question normally — MCP tools are not slash commands, so there is
+no `/coderag`:
+
+> Where are CPQ filter options defined across this repo?
+
+To force a tool on the first try, name it: *"Use the coderag_search tool to …"*.
+
+---
+
+## What the tools actually return
+
+Captured by running the tools against `examples/demo-repository`.
+
+### `coderag_search("where are failed payments retried?", limit=3)`
+
+```json
+[
+  {
+    "symbol": "payments.payment_service.PaymentService.retry_payment",
+    "type": "method",
+    "file": "payments/payment_service.py",
+    "lines": "33-54",
+    "score": 0.04672,
+    "why": ["graph_callee", "graph_caller", "graph_child", "lexical", "semantic"],
+    "tokens": 215
+  }
+]
+```
+
+Every hit explains **why** it was retrieved — `lexical` (full-text), `semantic`
+(vector), `exact_symbol`, or a graph reason such as `graph_caller` / `graph_test`.
+
+### `coderag_context("why can retry_payment leave an invoice pending?")`
+
+Returns `context` (the code text), `selected_symbols`, `token_accounting`, and a
+plain-language `measurement`:
+
+```
+Returned 1449 tokens of context instead of the 1654 tokens it would take to read
+the 8 file(s) containing this code (12.4% fewer input tokens).
+```
+
+```json
+{
+  "candidates_found": 38,
+  "candidates_selected": 27,
+  "candidate_tokens": 2240,
+  "context_tokens": 1449,
+  "token_reduction_from_candidates": 35.3,
+  "baseline_tokens": 1654,
+  "baseline_files": 8,
+  "tokens_saved_vs_files": 205,
+  "reduction_vs_files": 12.4
+}
+```
+
+Symbols come back grouped by priority — target first, then dependencies, callers,
+tests:
+
+```json
+[
+  {"category": "target",          "symbol": "…PaymentService.retry_payment",   "lines": "33-54", "tokens": 215},
+  {"category": "implementation",  "symbol": "…PaymentService.__init__",        "lines": "13-21", "tokens": 51},
+  {"category": "dependencies",    "symbol": "…PaymentService.process_payment", "lines": "23-31", "tokens": 75}
+]
+```
+
+> **Note the 12.4%.** That's the *demo* repo — 11 tiny files, where retrieval
+> reaches most of the codebase and the saving is small. On a real backend the
+> same measurement runs far higher (75% has been observed). Run
+> `coderag context "…" --measure` on your own repo for your number; don't trust
+> either figure as representative.
+
+---
+
+## The five tools
+
+| Tool | Use |
+|---|---|
+| `coderag_context` | Budgeted context for a question (target + deps + callers + tests) |
+| `coderag_search` | Ranked symbols with file/lines/score/why |
+| `coderag_symbol` | Full source of one symbol by qualified name |
+| `coderag_repositories` | Which repos are indexed, and at which commit |
+| `coderag_index` | Index / re-index (`incremental: true` for a fast update) |
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `/mcp` doesn't list `coderag` | Server not registered, or `.mcp.json` is not in the project root. Reload the window. |
+| Listed but **failed** | Run the command by hand: `CODERAG_DATABASE_URL=… /abs/path/coderag-mcp`. A healthy server sits silently on stdin (Ctrl-C to exit); a traceback tells you what's wrong. |
+| "command not found" | Use the absolute path from `which coderag-mcp`. |
+| "no repositories indexed yet" | Run `coderag index . --name myproject`. |
+| "multiple repositories; pass --repo" | Set `CODERAG_DEFAULT_REPOSITORY`. |
+| Tools connected but never called | The `CLAUDE.md` nudge is missing — see step 4. |
+| Results reference code that moved | Re-index: `coderag index . --name myproject --incremental`. |

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "hatchling.build"
 # command are both `coderag`. Plain "coderag" is taken on PyPI by an unrelated project,
 # and "code-rag" is rejected as too similar (PyPI collapses -/_/. when comparing names).
 name = "coderag-ai"
-version = "0.3.4"
+version = "0.4.0"
 description = "Token-efficient, structure-aware Code Intelligence + RAG for private source repositories."
 readme = "README.md"
 requires-python = ">=3.12"

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/src/coderag/cli/main.py

@@ -80,6 +80,97 @@ def localdb_status(
     console.print(f"[green]running (pid {pid})[/]" if pid else "[yellow]not running[/]")
 
 
+@app.command()
+def setup(
+    path: str = typer.Argument(".", help="Repository to index (default: current dir)."),
+    name: str | None = typer.Option(None, "--name", help="Repository name."),
+    mcp: bool = typer.Option(True, "--mcp/--no-mcp", help="Register with Claude Code."),
+    claude_md: bool = typer.Option(True, "--claude-md/--no-claude-md",
+                                   help="Append the retrieval nudge to CLAUDE.md."),
+) -> None:
+    """One command: start the database, migrate, index, and wire up Claude Code."""
+    from pathlib import Path
+
+    from coderag import localdb
+    from coderag.core.config import get_settings
+    from coderag.db.migrate import upgrade_to_head
+    from coderag.setup_flow import (
+        SetupResult,
+        append_nudge,
+        claude_md_needs_nudge,
+        register_mcp,
+    )
+
+    repo_path = Path(path).expanduser().resolve()
+    repo_name = name or repo_path.name
+    res = SetupResult(repository=repo_name)
+
+    # 1. database — reuse an already-configured one, else start the local server
+    import os
+
+    if os.environ.get("CODERAG_DATABASE_URL"):
+        res.database_url = get_settings().database_url
+        res.skip("using CODERAG_DATABASE_URL from the environment")
+    else:
+        try:
+            res.database_url = localdb.start()
+            res.ok("local PostgreSQL running (URL recorded; no export needed)")
+        except RuntimeError as exc:
+            res.warn(str(exc).splitlines()[0])
+            console.print(f"[red]{exc}[/]")
+            raise typer.Exit(1) from None
+
+    # 2. schema
+    try:
+        upgrade_to_head(res.database_url)
+        res.ok("database schema up to date")
+    except Exception as exc:
+        res.warn(f"migrations failed: {str(exc)[:120]}")
+        console.print(f"[red]Migrations failed:[/] {exc}")
+        raise typer.Exit(1) from None
+
+    # 3. index
+    get_settings.cache_clear()
+    os.environ["CODERAG_DATABASE_URL"] = res.database_url or ""
+    with session_scope() as session:
+        from coderag.service import run_index
+
+        repo, stats = run_index(session, str(repo_path), repo_name)
+        res.symbols = stats.symbols_indexed
+    res.ok(f"indexed {repo_name}: {stats.files_indexed} files, "
+           f"{stats.symbols_indexed} symbols, {stats.relationships_created} relationships")
+
+    # 4. Claude Code MCP registration
+    if mcp:
+        done, msg = register_mcp("coderag", res.database_url or "", repo_name)
+        (res.ok if done else res.warn)(msg)
+    else:
+        res.skip("MCP registration skipped (--no-mcp)")
+
+    # 5. the nudge — without it Claude Code never calls the tools
+    if claude_md:
+        target = repo_path / "CLAUDE.md"
+        if claude_md_needs_nudge(target):
+            append_nudge(target)
+            res.ok(f"added the retrieval nudge to {target}")
+        else:
+            res.skip("CLAUDE.md already contains the nudge")
+    else:
+        res.skip("CLAUDE.md untouched (--no-claude-md)")
+
+    icons = {"ok": "[green]✓[/]", "skip": "[dim]·[/]", "warn": "[yellow]![/]"}
+    console.print("\n[bold]CodeRAG setup[/]")
+    for status, msg in res.steps:
+        console.print(f"  {icons[status]} {msg}")
+    console.print(
+        "\nTry it:  [bold]coderag search \"where is X handled?\"[/]\n"
+        "In Claude Code: run [bold]/mcp[/] (expect 'coderag' connected), then ask a "
+        "question normally — MCP tools are not slash commands.\n"
+        "Dashboard: [bold]uvicorn coderag.api.app:app --port 8000[/] "
+        "-> http://localhost:8000/dashboard"
+    )
+
+
 @app.command()
 def migrate(
     database_url: str | None = typer.Option(

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/src/coderag/core/config.py

@@ -12,6 +12,19 @@ from functools import lru_cache
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+COMPOSE_DATABASE_URL = "postgresql+psycopg://coderag:coderag@localhost:5432/coderag"
+
+
+def _default_database_url() -> str:
+    """Fall back to the URL written by `coderag localdb start`, else compose's."""
+    from pathlib import Path
+
+    try:
+        value = (Path.home() / ".coderag" / "database_url").read_text().strip()
+    except OSError:
+        return COMPOSE_DATABASE_URL
+    return value or COMPOSE_DATABASE_URL
+
 
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(
@@ -23,9 +36,9 @@ class Settings(BaseSettings):
 
     # ---- Database -------------------------------------------------------
     # A libpq URL. In dev/test the pgserver fixture overrides this.
-    database_url: str = Field(
-        default="postgresql+psycopg://coderag:coderag@localhost:5432/coderag"
-    )
+    # Resolution order: CODERAG_DATABASE_URL env/.env -> the URL recorded by
+    # `coderag localdb start` -> the docker-compose default.
+    database_url: str = Field(default_factory=lambda: _default_database_url())
     db_echo: bool = False
 
     # Default repository name used when a request doesn't name one (handy for the

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/src/coderag/git/repo.py

@@ -44,6 +44,21 @@ class GitRepo:
         except (subprocess.CalledProcessError, FileNotFoundError):
             return False
 
+    def commit_exists(self, sha: str) -> bool:
+        """True if ``sha`` resolves to a commit object in this repository.
+
+        A rebase, amend, or force-push can orphan a previously-indexed commit;
+        diffing against it would fail, so callers check first and fall back to a
+        full index.
+        """
+        if not sha:
+            return False
+        try:
+            self._git("cat-file", "-e", f"{sha}^{{commit}}")
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return False
+
     def current_commit(self) -> str | None:
         try:
             return self._git("rev-parse", "HEAD").strip()

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/src/coderag/indexing/indexer.py

@@ -9,6 +9,7 @@ Phase 8.
 from __future__ import annotations
 
 import hashlib
+import subprocess
 import time
 from dataclasses import dataclass
 
@@ -155,6 +156,14 @@ class Indexer:
         head = git.current_commit()
         if not git.is_git() or not base:
             return self.full_index(repo)
+        if not git.commit_exists(base):
+            # The previously-indexed commit is gone (rebase / amend / force-push),
+            # so there is no valid diff base. Rebuild instead of failing.
+            log.warning(
+                "incremental_index.base_missing", repository=repo.name,
+                base=base[:12], action="falling back to full index",
+            )
+            return self.full_index(repo)
 
         started = time.perf_counter()
         run = IndexingRun(repository_id=repo.id, mode="incremental", status="running",
@@ -166,7 +175,18 @@ class Indexer:
         self._pending_rels = []
         stats = IndexStats(commit_sha=head)
         try:
-            diff = git.diff(base, head or "HEAD")
+            try:
+                diff = git.diff(base, head or "HEAD")
+            except subprocess.CalledProcessError:
+                # Unexpected diff failure (shallow clone, corrupt object, …):
+                # a full rebuild is always correct, so prefer it over erroring.
+                log.warning(
+                    "incremental_index.diff_failed", repository=repo.name,
+                    action="falling back to full index",
+                )
+                run.status = "superseded"
+                self.session.flush()
+                return self.full_index(repo)
             changed = [p for p in diff.changed if should_index(p, self.extra_ignore)]
             gone = set(changed) | set(diff.deleted)
             for path in gone:

{coderag_ai-0.3.4 → coderag_ai-0.4.0}/src/coderag/localdb.py

@@ -13,6 +13,18 @@ from __future__ import annotations
 from pathlib import Path
 
 DEFAULT_PGDATA = Path.home() / ".coderag" / "pgdata"
+# `localdb start` records its URL here so other commands (and the MCP server)
+# find the database automatically, without the user exporting anything.
+URL_FILE = Path.home() / ".coderag" / "database_url"
+
+
+def saved_url() -> str | None:
+    """The URL recorded by the most recent `localdb start`, if any."""
+    try:
+        value = URL_FILE.read_text().strip()
+    except OSError:
+        return None
+    return value or None
 
 
 def _require_pgserver():
@@ -51,6 +63,13 @@ def start(pgdata: Path | str | None = None) -> str:
     server = pgserver.get_server(str(path), cleanup_mode=None)
     url = sqlalchemy_url(server.get_uri())
     _ensure_vector_extension(url)
+    # Record it (default location only) so later commands need no env var.
+    if Path(pgdata or DEFAULT_PGDATA).expanduser() == DEFAULT_PGDATA:
+        try:
+            URL_FILE.parent.mkdir(parents=True, exist_ok=True)
+            URL_FILE.write_text(url + "\n")
+        except OSError:  # pragma: no cover - convenience only, never fatal
+            pass
     return url