System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The claude-code-docs project serves as an unofficial, automated mirror of the official Claude Code documentation. Its primary purpose is to provide AI coding agents and developers with a local, version-pinned, and semantically searchable version of the documentation. This prevents the need to ingest large volumes of documentation into the LLM context by enabling on-demand access to specific markdown files.
The system is composed of a synchronization engine, a documentation distribution mechanism using the Agent Skills Kit (ASK), and a Claude Code plugin that intercepts web requests to optimize content delivery for AI consumption.
Sources: README.md:1-12, skills/claude-code-docs/SKILL.md:1-5
Core Components and Data Flow
The architecture is built around three main pillars: content synchronization, semantic search integration, and tool-use interception.
Documentation Synchronization
The synchronization process treats llms.txt as the source of truth for the documentation structure. A TypeScript-based sync engine (sync.ts) runs every 6 hours via GitHub Actions to rebuild the local docs/ directory.
The diagram shows how the remote manifest is used to rebuild the local documentation tree, ensuring that deletions on the source site are reflected as git deletions in the mirror.
Sources: sync.ts:1-7, README.md:14-18
Link Rewriting Logic
During synchronization, site-absolute links are transformed into relative links to facilitate offline browsing and local file resolution.
| Feature | Description |
|---|---|
| Local Resolution | Converts /en/slug to ./slug.md or ../slug.md based on directory depth. |
| Fallback | If a slug is not found in the local manifest, it retains the canonical https://code.claude.com/docs/en/ prefix. |
| Anchor Cleaning | Removes percent-encoding (e.g., %2F) from fragments to match GitHub's generated heading IDs. |
Sources: sync.ts:14-38
Integration with ASK (Agent Skills Kit)
The project leverages ASK and csp (Code Search Please) to provide semantic search capabilities over the mirrored documentation. This allows agents to perform high-level queries instead of reading entire files.
This flow ensures that agents only consume the most relevant portions of the documentation.
Sources: README.md:20-41, skills/claude-code-docs/SKILL.md:27-44
Claude Code Plugin and Hooks
The repository functions as a Claude Code plugin, utilizing a PreToolUse hook to optimize the WebFetch tool. This is defined in hooks/hooks.json and implemented in hooks/rewrite-docs-url.sh.
URL Rewriting Mechanism
When Claude attempts to fetch a standard documentation URL (HTML), the hook intercepts the request and redirects it to the raw markdown version. This avoids the overhead of the "HTML app shell."
Hook Configuration
The plugin configuration specifies how the command is executed within the Claude environment:
| Field | Value | Description |
|---|---|---|
matcher | WebFetch | Only intercepts requests from the WebFetch tool. |
type | command | Executes a shell script for the logic. |
command | bash ${CLAUDE_PLUGIN_ROOT}/hooks/rewrite-docs-url.sh | Path to the transformation script. |
permissionDecision | allow | Automatically approves the rewritten URL without a user prompt. |
Sources: hooks/hooks.json:4-16, hooks/rewrite-docs-url.sh:40-47, README.md:59-62
Error Handling and Resilience
The system includes several safeguards to prevent repository corruption:
- Fetch Retries: The
fetchTextfunction implements 3 retries with exponential backoff (1000 * attempt). - Atomic Runs: Any fetch failure aborts the synchronization before a partial or corrupted tree is committed to git.
- Manifest Validation: The sync script throws an error if the parsed manifest contains fewer than 10 pages, preventing accidental mass deletions.
Sources: sync.ts:8-12, sync.ts:41-55, sync.ts:63-64
Conclusion
The architecture of claude-code-docs provides a robust bridge between official web documentation and AI-native tooling. By combining scheduled synchronization, relative link rewriting, and tool-use interception via shell hooks, it enables efficient, offline-capable, and semantically searchable access to technical documentation.