Documentation Mirroring Features

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 Documentation Mirroring system is an automated infrastructure designed to track, download, and reformat official Claude Code documentation for use by AI agents and developers. It serves as an unofficial mirror that provides clean Markdown versions of content originally hosted as HTML, ensuring that updates, additions, and deletions from the canonical source are captured in Git history every six hours.

The system facilitates high-efficiency access to documentation through three primary mechanisms: a synchronization engine that rebuilds the document tree from a manifest, a local caching layer via the ask CLI for agentic workflows, and a Claude Code plugin that intercepts web requests to redirect tool calls from HTML pages to their raw Markdown counterparts.

Sources: README.md:1-13, sync.ts:1-7

Architecture and Synchronization Logic

The core of the mirroring feature is the sync.ts script, which treats the llms.txt file as the authoritative source of truth for the documentation structure. The synchronization process follows a "clean slate" approach where the local docs/ directory is purged and rebuilt on every run to ensure deletions in the source are reflected in the mirror.

Synchronization Workflow

The synchronization logic implements a concurrent fetch model with retry mechanisms to ensure reliability. It specifically handles link rewriting to transform site-absolute paths (suitable for a web server) into relative paths (suitable for local filesystem browsing or GitHub).

The diagram shows the sequence of events from manifest retrieval to the final writing of processed Markdown files.
Sources: sync.ts:1-12, sync.ts:60-91

Key Synchronization Components

Component	Description	Reference
llms.txt	The manifest listing all documentation pages. Used to define the scope of the sync.	sync.ts:60
llms-full.txt	A single-file bundle of the entire documentation suite.	sync.ts:69
rewriteLinks	Function that converts /en/slug links to ./slug.md or absolute URLs if the target isn't mirrored.	sync.ts:14-38
Concurrency	The system uses a CONCURRENCY limit of 10 and RETRIES of 3 for network resilience.	sync.ts:8-9

Sources: sync.ts:8-12, sync.ts:14-38, sync.ts:60-69

Agent Skill and Semantic Search

The repository integrates with the Agent Skills Kit (ask) to provide AI coding agents with lazy, on-demand access to documentation. This prevents context window saturation by allowing agents to search and retrieve only relevant snippets.

Search and Retrieval Flow

Agents utilize semantic search to find information without reading the entire 5MB documentation bundle. This is achieved through the csp (Code Search Please) utility.

This diagram illustrates how an agent interacts with the local mirror to perform efficient documentation queries.
Sources: README.md:27-50, skills/claude-code-docs/SKILL.md:23-48

Skill Execution Steps

1. Resolve Mirror: Uses ask src to locate the cached checkout path.
2. Semantic Search: Uses csp search or grep (as a fallback) to find relevant pages.
3. Grounding: The agent reads the specific pages and generates an answer citing canonical URLs.
4. Fallback: If local tools are missing, the system fetches llms.txt via WebFetch to find individual page URLs.

Sources: skills/claude-code-docs/SKILL.md:15-68

Plugin Hook: WebFetch Rewriting

A specialized PreToolUse hook is provided for the Claude Code CLI. This hook intercepts the WebFetch tool call whenever the model attempts to access a documentation URL at code.claude.com/docs.

URL Transformation Logic

The hook identifies standard HTML documentation URLs and appends .md to the path. This forces the fetcher to retrieve the clean Markdown "twin" instead of the full HTML application shell, reducing token waste and improving parsing accuracy for the AI.

The diagram outlines the logic used by the bash hook to redirect requests to raw markdown sources.
Sources: hooks/rewrite-docs-url.sh:11-39, README.md:54-65

Transformation Examples

Input URL	Rewritten URL
.../docs/en/agents	.../docs/en/agents.md
.../docs/en/hooks#anchor	.../docs/en/hooks.md
.../docs/en/agent-sdk/python?v=1	.../docs/en/agent-sdk/python.md

Sources: README.md:57-60, hooks/rewrite-docs-url.test.sh:18-22

Implementation Details

Hook Configuration

The hook is registered in hooks.json as a command type hook for the WebFetch matcher. It is configured with a 5-second timeout and executes via a bash script located in the plugin root.

{
  "matcher": "WebFetch",
  "hooks": [
    {
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/rewrite-docs-url.sh",
      "timeout": 5
    }
  ]
}

Sources: hooks/hooks.json:1-17

Link Sanitization in Sync

During the sync process, the script handles specific GitHub-flavored Markdown requirements. For example, it removes slashes from generated heading IDs because GitHub removes them while the source documentation site percent-encodes them (e.g., %2F).

const githubAnchor = anchor.replace(/%2F/gi, "");
return `${target}${githubAnchor}`;

Sources: sync.ts:23-25

Conclusion

The Documentation Mirroring system provides a robust bridge between high-latency, token-heavy web documentation and low-latency, token-efficient agentic workflows. By combining periodic synchronization, semantic search capabilities via the ask CLI, and real-time request interception through Claude Code hooks, it ensures that AI agents always have access to canonical, well-formatted technical information without manually managing documentation updates.