Synchronization Strategy

Relevant source files

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

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

The Synchronization Strategy for claude-code-docs defines how the repository mirrors official Claude Code documentation from code.claude.com into a version-controlled GitHub repository. This process ensures that AI agents and developers have access to a clean, markdown-based representation of the documentation that supports semantic search, git history tracking, and offline usage.

The core of this strategy is centered around a periodic sync (every 6 hours) that treats the official llms.txt file as the absolute source of truth. By rebuilding the local documentation tree on every run, the system ensures that additions, modifications, and deletions in the source documentation are accurately reflected in the git history.
Sources: README.md:1-15, sync.ts:1-10

Core Synchronization Logic

The synchronization is implemented in sync.ts using the Bun runtime. It follows a destructive rebuild pattern where the local docs/ directory is purged and recreated to ensure a perfect mirror of the remote state.

Manifest Resolution

The process begins by fetching the llms.txt manifest from the base URL https://code.claude.com/docs. This manifest contains URLs for all individual documentation pages in markdown format. The sync script validates that the manifest contains a minimum threshold of pages (at least 10) to prevent accidental mass deletions due to a broken upstream manifest.
Sources: sync.ts:1-15, sync.ts:54-61

Parallel Processing and Resilience

To optimize performance and handle network instability, the system employs the following configuration:

Parameter	Value	Description
BASE	https://code.claude.com/docs	The root URL for documentation sources.
CONCURRENCY	10	The number of simultaneous fetch operations.
RETRIES	3	Number of attempts for a failed fetch before aborting the sync.

Sources: sync.ts:7-9, sync.ts:40-52

Data Flow Diagram

The following diagram illustrates the high-level synchronization flow from manifest retrieval to local file writes.

The flow ensures that any download failure aborts the entire run before a commit occurs, preventing transient network errors from appearing as fake deletions in git.
Sources: README.md:18-22, sync.ts:54-82

Link Transformation Strategy

A critical part of the synchronization is the rewriteLinks function. Official documentation pages use site-absolute paths (e.g., /en/sub-agents) which do not work when browsing the repository as local files or on GitHub.

The strategy rewrites these links based on the following logic:

1. Known Slugs: If a link points to a slug present in the current llms.txt manifest, it is rewritten as a relative path to a local .md file.
2. External Links: If the slug is not recognized, it is converted to a canonical absolute URL to ensure the link remains functional.
3. Fragment Normalization: GitHub-style anchors are handled by removing slashes from generated heading IDs to match GitHub's markdown rendering.

function rewriteLinks(content: string, rel: string, knownSlugs: Set<string>): string {
  const fromDir = dirname(rel);
  const resolve = (slug: string, anchor: string): string => {
    if (knownSlugs.has(slug)) {
      let target = relative(fromDir, `${slug}.md`);
      if (!target.startsWith(".")) target = `./${target}`;
      const githubAnchor = anchor.replace(/%2F/gi, "");
      return `${target}${githubAnchor}`;
    }
    return `${BASE}/en/${slug}${anchor}`;
  };
  // ... regex replacements for Markdown and JSX links ...
}

Sources: sync.ts:15-38

Consumption and Integration Strategy

The synchronized documentation is consumed through two primary mechanisms: the Agent Skills Kit (ASK) and a Claude Code plugin hook.

Agent Skills Kit (ASK) Integration

ASK uses the synchronized mirror to provide lazy, on-demand access to documentation. Instead of including the full 5MB documentation set in the LLM context, it resolves the local mirror path and uses semantic search.

1. Resolution: ask src identifies the cached checkout of the mirror.
2. Search: csp (Code Search Please) performs semantic search over the individual markdown files in docs/.
3. Context Injection: Only the relevant sections or pages found via search are provided to the agent.
   Sources: README.md:25-50, skills/claude-code-docs/SKILL.md:20-45

PreToolUse Hook Transformation

The repository includes a PreToolUse hook for Claude Code that intercepts WebFetch calls. When an agent attempts to fetch an HTML documentation URL, the hook rewrites it to the .md source URL.

The hook uses jq to modify the tool input and provides a permissionDecision: "allow" to execute the rewritten fetch without user intervention.
Sources: hooks/rewrite-docs-url.sh:25-45, README.md:52-65, hooks/hooks.json:1-17

Summary

The synchronization strategy ensures a high-fidelity, machine-readable mirror of Claude Code documentation. By combining periodic destructive syncs, automated link rewriting, and integration hooks, the project provides a reliable infrastructure for AI agents to query and understand Claude Code features without the overhead of processing HTML or excessive context windows.
Sources: README.md:1-10, sync.ts:1-5