Caching and Offline Support

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• skills/claude-code-docs/SKILL.md
• sync.ts
• hooks/hooks.json
• hooks/rewrite-docs-url.sh
• hooks/rewrite-docs-url.test.sh

The claude-code-docs project implements a robust caching and offline support system by mirroring the official Claude Code documentation into a local repository. This architecture allows AI coding agents and developers to access documentation without constant reliance on live web fetches, reducing context window bloat and improving performance.

The system utilizes a combination of automated synchronization scripts, a local file-based mirror, and the Agent Skills Kit (ASK) to provide "lazy" on-demand access to documentation. By pinning a local checkout of the docs, the system ensures that tools can resolve information even in restricted network environments or offline sandboxes.

Sources: README.md:1-12, skills/claude-code-docs/SKILL.md:16-18

Local Mirror Architecture

The core of the offline support is the documentation mirror, which tracks the official site's state within a Git history. This allows for version-pinned local checkouts that can be queried semantically.

Documentation Synchronization

The synchronization logic is managed by sync.ts, which treats the official llms.txt manifest as the source of truth. It rebuilds the docs/ directory from scratch during each run to ensure consistency, including the handling of page deletions.

The diagram above illustrates the atomic rebuild process that prevents partial or corrupted documentation states from being committed.
Sources: sync.ts:6-15, sync.ts:66-88, README.md:14-19

Link Rewriting for Local Browsing

To support offline browsing and local file resolution, sync.ts includes a rewriteLinks function. This transforms site-absolute paths (e.g., /en/hooks) into relative file paths (e.g., ../hooks.md) if the target exists in the mirror.

Feature	Implementation	Purpose
Markdown Links	Regex for ](/en/slug)	Ensures local cross-references work in IDEs/Git.
JSX/MDX Links	Regex for href="/en/slug"	Supports component-based documentation links.
Fallback	Canonical URL	Points to live site if page is not mirrored.

Sources: sync.ts:16-43

ASK CLI and Semantic Search

The project integrates with the ASK (Agent Skills Kit) to provide cached access and semantic search capabilities, which are critical for offline operations where broad internet access may be limited.

Cached Checkout Resolution

The system uses ask src or ask docs to resolve the path to a cached checkout. On the first use, it clones the repository to a local directory (typically ~/.ask/github/...). Subsequent calls return the local path immediately.

Semantic Search (csp)

To avoid loading the entire 5MB documentation bundle into an LLM's context, the csp (Code Search Please) tool is used for semantic search over the local docs/ directory. This allows agents to retrieve only the top-k relevant pages.
Sources: README.md:32-44, skills/claude-code-docs/SKILL.md:26-38

Offline Fallback Mechanisms

The system is designed with multiple levels of fallback to ensure functionality regardless of the environment's connectivity or tool availability.

Tool Hierarchy

The claude-code-docs skill attempts to resolve documentation in the following order:

1. ASK CLI + csp: Semantic search over a version-pinned local mirror.
2. npx/bunx: Run ASK/csp via package runners if not on the system PATH.
3. Grep: Fallback to keyword search over the mirror if semantic search tools are missing.
4. WebFetch: Final fallback to fetching live markdown files if no local mirror is available.

Sources: skills/claude-code-docs/SKILL.md:16-56, README.md:58-64

PreToolUse URL Rewriting

For cases where a WebFetch is required (the final fallback), the project includes a Claude Code plugin hook. This hook intercepts requests to code.claude.com/docs and rewrites them to point directly to the .md source file.

# hooks/rewrite-docs-url.sh snippets
# Rewrites https://code.claude.com/docs/en/agents -> .../agents.md
path="${url%%#*}"
path="${path%%\?*}"
# ... logic to ensure it's a documentation page ...
jq --arg url "${path}.md" '{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "allow",
    updatedInput: (.tool_input | .url = $url)
  }
}'

This ensures that even when falling back to the web, the agent receives clean, token-efficient markdown rather than a heavy HTML application shell.
Sources: hooks/rewrite-docs-url.sh:12-40, hooks/hooks.json:1-17

Summary of Caching Components

Component	Role	File Reference
docs/	Local directory containing mirrored markdown files.	README.md
llms.txt	Manifest file used to verify and sync documentation.	sync.ts
ask	CLI for managing local checkouts and skill generation.	README.md
csp	Tool for semantic search over the local cache.	README.md
hooks.json	Configuration for URL interceptors during fetch.	hooks/hooks.json

The combination of a local Git-tracked mirror and the ASK CLI's caching mechanisms ensures that developers have a reliable, versioned, and offline-capable source of truth for Claude Code documentation.
Sources: README.md:1-10, sync.ts:60-65