Semantic Search with CSP
Relevant source files
The following files were used as context for generating this wiki page:
Semantic Search with CSP (Code Search Please) is a core functionality of the claude-code-docs project, enabling AI coding agents to perform token-efficient, natural language queries over a local mirror of the Claude Code documentation. Instead of loading the entire documentation corpus into an LLM's context window, CSP allows for targeted retrieval of relevant markdown sections based on the user's intent.
Sources: README.md:1-5, README.md:32-34, skills/claude-code-docs/SKILL.md:1-5
Architecture and Integration
The semantic search system operates as a middle layer between the user (or AI agent) and the local documentation mirror. It relies on a version-pinned checkout of the repository resolved via the ask CLI.
Component Interaction
The following diagram illustrates how the ask CLI coordinates with csp to resolve documentation queries.
The system prioritizes semantic search via csp, but includes a graceful degradation path to keyword-based grep or direct WebFetch if local tools are unavailable.
Sources: skills/claude-code-docs/SKILL.md:14-25, README.md:42-45
Core Search Logic
The search logic is primarily encapsulated in the ask search command and the integrated Skill definition. It targets the docs/ directory specifically to avoid duplicating results from the combined llms-full.txt bundle.
Search Execution Flow
- Mirror Resolution: The system uses
ask srcto find the root of the cached documentation checkout. - Indexing: CSP indexes the per-page markdown files within the
docs/subdirectory. - Querying: The natural language question is processed against the index to find the "Top-K" most relevant matches.
Search Configuration and CLI Usage
Users and agents interact with CSP through specific CLI flags. The primary interface is the ask command, which acts as a wrapper for csp.
Key Commands and Arguments
| Command | Argument/Flag | Description |
|---|---|---|
csp search | "$question" "$DOCS" | Direct invocation of the CSP search engine. |
--content | docs | Scopes search to the docs/ folder for token efficiency. |
--top-k | 8 (default) | Specifies the number of relevant results to return. |
ask search | github:repo [query] | Delegates to CSP for search over a managed repo. |
Sources: skills/claude-code-docs/SKILL.md:27-38, README.md:35-41
Data Preparation for Search
The documentation mirror is prepared via sync.ts, which ensures that the search index remains accurate.
- Source of Truth: The
llms.txtmanifest defines which pages are active. - Link Rewriting: Local cross-links are rewritten to
.mdformat so that retrieved search results contain valid local file references. - Cleanup: The
docs/directory is rebuilt from scratch on every sync to prevent stale pages from appearing in search results.
Sources: sync.ts:1-15, sync.ts:60-65
Integration with Claude Code Plugin
The semantic search capability is also exposed as a skill within the Claude Code plugin. When a user asks a question about Claude Code, the plugin executes a specific workflow:
- Resolves the mirror via
ask src. - Executes
csp searchwith--top-k 8. - Reads the resulting matching pages entirely (leveraging their small size).
- Generates an answer citing canonical URLs (e.g., mapping
docs/hooks.mdback tohttps://code.claude.com/docs/en/hooks).
Conclusion
Semantic Search with CSP provides a high-performance, context-aware retrieval system for the Claude Code documentation. By integrating with the ask CLI and utilizing a local markdown mirror, it enables AI agents to find precise information without the overhead of full-text ingestion, while maintaining a robust fallback system for varied environments.