← Home

Semantic search

Give your coding agent an MCP tool that semantically searches every plan, spike, bug, and review in .shipper/ — powered by a small local embeddings model.

  1. 1

    Install

    Install the Shipper CLI if you have not already. Semantic search ships with the binary — no extra packages.

  2. 2

    Register

    Register the MCP server with your coding agents:

    shipper mcp install

    This writes the Shipper entry for Claude Code, Cursor, and opencode (or one agent via --agent), prefetches the embedding model, and asks you to restart the agent. Use --no-download to skip the prefetch.

  3. 3

    Use

    In your agent, call shipper_search with a short natural-language query. Bundled skills (shipper-plan, shipper-spike, shipper-bug, shipper-build) do this automatically when the tool is available. From a terminal you can also run shipper search or shipper index.

  4. 4

    Manage

    The shared embedding server runs on 127.0.0.1 and shuts down after 15 idle minutes by default. Check or stop it anytime:

    shipper embed status
    shipper embed stop
    shipper embed start --idle-minutes 30

Tools

  • shipper_search — Semantic search across plans, spikes, bugs, and reviews.
  • shipper_similar — Find documents similar to an existing Shipper file.
  • shipper_get_doc — Read a Shipper markdown file (optional line range).
  • shipper_list_docs — List indexed Shipper documents.
  • shipper_reindex — Rebuild or refresh the search index.

What gets downloaded

On first use, Shipper downloads a pinned llama.cpp build from GitHub (about 12–17 MB depending on platform) and an 84 MB GGUF model from Hugging Face (nomic-embed-text-v1.5 Q4_K_M). Both are SHA-256 verified into ~/.cache/shipper/. No document text or embeddings leave your machine. Remove everything with shipper mcp uninstall, shipper embed stop, and rm -rf ~/.cache/shipper. See also the skills docs for how agents use search during plan and build.