Search and Answer Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Search and Answer Flow is a core capability of the claude-code-docs project, designed to allow AI agents to query official Claude Code documentation efficiently. It leverages a local, version-pinned mirror of the documentation to perform semantic searches, avoiding the overhead of including massive documentation sets directly into the LLM context window.
This flow utilizes a combination of the ask CLI for repository management and the csp tool for semantic searching. It serves as a secondary retrieval mechanism when direct URL fetching (enhanced by URL rewriting hooks) is insufficient or when the user provides a broad natural language question about Claude Code features, configuration, or support.
Sources: skills/claude-code-docs/SKILL.md:1-12, README.md:21-28
System Architecture
The architecture consists of three main stages: mirror resolution, semantic search, and information synthesis. The system is built to be resilient, falling back to traditional text searching (grep) or live web fetching if specialized tools are unavailable.
Component Interaction
The following diagram illustrates the interaction between the user's question, the local documentation mirror, and the search tools.
Core Flow Stages
1. Mirror Resolution
The flow begins by identifying the local path of the documentation mirror. This mirror is maintained as a cached checkout of the claude-code-docs repository. The ask src command is used to find the root directory where the llms.txt manifest and the docs/ directory reside.
| Tool Command | Purpose |
|---|---|
ask src <repo> | Prints the root of the cached checkout. |
ask docs <repo> | Resolves the specific path to the mirrored documentation files. |
Sources: skills/claude-code-docs/SKILL.md:18-22, README.md:31-35
2. Search Strategy
The system prioritizes semantic search over simple keyword matching to improve accuracy for complex queries.
- Primary (Semantic): Uses
csp(Code Search Please) to perform token-efficient semantic search across thedocs/directory. It typically targets the top 8-10 results. - Secondary (Grep): If
cspis unavailable, the system falls back togrep -rilusing 2-3 distinct keyword variants derived from the user's query. - Tertiary (Manifest): The
llms.txtfile is used as a "fast-track" summary to shortlist pages when keyword noise is high.
Sources: skills/claude-code-docs/SKILL.md:28-44, README.md:40-52
3. Answer Generation and Citation
Once relevant pages are identified, the flow extracts the content and synthesizes an answer. A critical requirement of this flow is that every claim must be grounded in the documentation.
- Language Mapping: Answers are provided in the user's language, but technical identifiers (flags, JSON fields) remain verbatim.
- Citation Mapping: Local file paths are mapped back to canonical URLs. For example,
$DOCS/hooks.mdis cited ashttps://code.claude.com/docs/en/hooks.
Sources: skills/claude-code-docs/SKILL.md:48-53
WebFetch Integration and URL Rewriting
While the Search and Answer Flow handles general questions, specific URL lookups are optimized via a PreToolUse hook. This hook intercepts WebFetch calls to official documentation URLs and rewrites them to point to clean markdown sources.
The rewriting logic excludes files that already have extensions (like .png or .txt) and only targets paths under the /docs/<locale>/ segment.
Sources: hooks/hooks.json:1-18, hooks/rewrite-docs-url.sh:11-37, README.md:58-69
Implementation Details
Link Persistence logic
During the synchronization process (via sync.ts), site-absolute links are rewritten to be relative to the local file structure. This ensures that the Search and Answer Flow can navigate between pages in a local environment (like GitHub or a local filesystem) without breaking.
function rewriteLinks(content: string, rel: string, knownSlugs: Set<string>): string {
// ... logic to convert /en/sub-agents to ../sub-agents.md
}
Sources: sync.ts:15-38
Technical Requirements
The flow relies on specific environmental configurations:
- Concurrency: Documentation syncing uses a concurrency limit of 10 and 3 retries for robustness.
- Mirror Integrity: A minimum of 10 pages must be found in the manifest; otherwise, the sync (and subsequent search capability) fails to prevent mass deletions.
Sources: sync.ts:7-9, 65-66
Summary
The Search and Answer Flow provides a robust, multi-layered approach to documentation retrieval. By combining a versioned local mirror, semantic search via csp, and a fallback system that includes grep and optimized WebFetch hooks, it ensures that AI agents can provide accurate, cited information about Claude Code without consuming excessive context or relying on outdated internal knowledge.