Fallback Mechanisms
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Fallback mechanisms in the claude-code-docs project ensure system resilience and data availability when primary tools or network resources are unavailable. These mechanisms are implemented across documentation retrieval, semantic search, and synchronization processes. The project prioritizes local, version-pinned mirrors of documentation, falling back to live web fetching or basic text searching only when optimized paths fail.
Sources: skills/claude-code-docs/SKILL.md:14-16, README.md:54-58
Retrieval Fallback Logic
The documentation retrieval system follows a multi-tiered fallback strategy to resolve the location of the Claude Code documentation mirror. The system first attempts to use the ask CLI for managed path resolution, then falls back to npx execution, and finally resorts to direct WebFetch if the CLI tools are completely unavailable (e.g., in offline sandboxes).
Resolve Docs Mirror Flow
The resolution process attempts to find the cached checkout path using the following hierarchy:
This diagram illustrates the prioritized sequence of resolution methods for locating the local documentation mirror.
Sources: skills/claude-code-docs/SKILL.md:18-30
WebFetch Fallback
When CLI-based local mirrors are unavailable, the system fetches the manifest directly from the live site.
- Fetch
https://code.claude.com/docs/llms.txt. - Parse the manifest to identify relevant page URLs.
- Fetch individual pages using the
.mdextension suffix.
Sources: skills/claude-code-docs/SKILL.md:65-68
Search Fallback Logic
The system implements a tiered search strategy that prioritizes high-performance semantic search but degrades gracefully to basic keyword matching.
| Tier | Method | Tool | Condition |
|---|---|---|---|
| 1 | Semantic Search | csp | Tool is on system PATH |
| 2 | Managed Semantic | npx @pleaseai/csp | csp missing from PATH |
| 3 | Local Grep | grep -ril | Search tools missing or fail |
| 4 | Manifest Scan | llms.txt | Used to shortlist pages when search is noisy |
Sources: skills/claude-code-docs/SKILL.md:32-52, README.md:46-52
Search Execution Sequence
The search fallback ensures that information can still be retrieved even if specialized embedding-based search tools are not installed.
Sources: skills/claude-code-docs/SKILL.md:32-52
Network and Synchronization Fallbacks
The sync.ts utility and the URL rewriting hooks include specific logic to handle transient failures and ensure data integrity.
Sync Retries and Aborts
The synchronization script uses a retry mechanism for network requests to handle transient errors. However, it implements a "fail-fast" policy for structural issues to prevent data corruption.
- Network Retries: Performs up to 3 attempts with exponential backoff (1000ms * attempt number).
- Integrity Check: If the parsed manifest contains fewer than 10 pages, the process throws an error and aborts to prevent accidental mass deletions in the git history.
Sources: sync.ts:11-12, sync.ts:46-56, sync.ts:66-67
URL Rewriting Fallbacks
The rewrite-docs-url.sh hook intercepts WebFetch calls to provide clean markdown. If the URL does not match specific criteria (e.g., it is already a file, not a documentation page, or from a different domain), the hook exits silently with code 0. This allows the original tool call to proceed without modification.
Link Resolution Fallback
In sync.ts, the rewriteLinks function handles cross-page navigation. It attempts to resolve site-absolute paths (e.g., /en/sub-agents) to local relative file paths (e.g., ../sub-agents.md). If the target slug is not part of the known mirrored pages, it falls back to the canonical absolute URL to ensure the link remains functional.
Sources: sync.ts:24-31
Conclusion
Fallback mechanisms in claude-code-docs are designed to prioritize local performance and clean data (Markdown via csp and local mirrors) while ensuring the system remains functional through standard web protocols and basic text processing when optimized environments are unavailable. This multi-layered approach provides a robust interface for agents to access documentation under varying environmental constraints.