Extending the Hook System

Relevant source files

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

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

The Hook System in the claude-code-docs project provides a mechanism to intercept and modify tool executions within the Claude Code environment. Its primary objective is to enhance the interaction between the AI agent and web-based documentation by performing real-time transformations on tool inputs, such as URL rewriting for the WebFetch tool. This ensures that the agent receives clean, machine-readable content (Markdown) instead of complex HTML structures.

By implementing hooks like PreToolUse, the system can gain fine-grained control over permissions and tool parameters. This allows for seamless integration of version-pinned documentation mirrors and automated semantic search capabilities, as described in the README.md and SKILL.md files.

Sources: README.md:65-72, hooks/hooks.json:1-16, skills/claude-code-docs/SKILL.md:1-10

Hook Architecture and Configuration

The hook system is defined through a JSON configuration that maps specific hook events to executable commands. The core configuration resides in hooks/hooks.json.

Hook Definition

The system currently implements the PreToolUse hook event, specifically targeting the WebFetch tool. When this tool is invoked, the system executes a shell script defined in the command field.

Configuration Field	Description
description	A human-readable summary of the hook's purpose.
hooks	The root object containing hook event definitions.
PreToolUse	Event triggered before a tool is executed.
matcher	Identifies the specific tool (e.g., WebFetch) to intercept.
type	The execution method (e.g., command).
command	The specific script or binary to run.
timeout	Execution limit in seconds.

Sources: hooks/hooks.json:1-16

Execution Flow

The flow follows a sequence where tool input is intercepted, passed to a handler, and then returned with modifications and permission decisions.

The diagram above illustrates how the PreToolUse hook intercepts a request before it reaches the WebFetch tool, modifying the target URL.
Sources: hooks/hooks.json:1-16, hooks/rewrite-docs-url.sh:1-46

URL Rewriting Logic

The rewrite-docs-url.sh script serves as the primary implementation of the PreToolUse hook. It specifically targets requests to code.claude.com/docs.

Processing Steps

1. Input Parsing: Reads JSON from stdin to extract .tool_input.url.
2. Domain Filtering: Only processes URLs starting with https://code.claude.com/docs/.
3. Normalization: Removes URL fragments (#) and query parameters (?) to find the base path.
4. File Type Check: Ignores URLs that already point to raw files (e.g., .md, .txt, images).
5. Locale Validation: Ensures the URL targets a specific page under a locale segment (e.g., /docs/en/agents) rather than the root directory.
6. Transformation: Appends .md to the path and constructs a response JSON.

Sources: hooks/rewrite-docs-url.sh:7-36

Hook Response Structure

The script returns a JSON object containing hookSpecificOutput. This object controls whether the tool execution proceeds and what parameters it uses.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "...",
    "updatedInput": {
      "url": "https://code.claude.com/docs/en/page.md"
    }
  }
}

Sources: hooks/rewrite-docs-url.sh:38-46

Integration with Documentation Sync

Hooks work in tandem with the synchronization logic found in sync.ts, which maintains the local mirror of the documentation.

Synchronization Component Relationships

The sync.ts script fetches the llms.txt manifest and rebuilds the docs/ directory. It includes logic to rewrite internal links within the Markdown files to maintain local consistency while falling back to canonical URLs for external resources.

The flow represents how the build-time sync process and the run-time hook system both target the same Markdown-based source structure.
Sources: sync.ts:1-73, README.md:20-25

Testing and Verification

The hook system includes a dedicated test suite, hooks/rewrite-docs-url.test.sh, which validates the rewriting logic against various URL patterns.

Test Scenarios

The test suite ensures that:

• Standard documentation pages are correctly rewritten to .md.
• URLs with fragments or query parameters are cleaned.
• Existing file extensions are left untouched (silent pass-through).
• External domains are ignored.
• Tool inputs other than the URL (e.g., prompt) are preserved in the updatedInput object.

Sources: hooks/rewrite-docs-url.test.sh:11-44

Test Result Summary

Test Type	Input Example	Expected Behavior
Rewrite	.../docs/en/agents	Rewrites to .../docs/en/agents.md
Fragment	.../hooks#control	Strips #control, appends .md
Pass-through	.../llms.txt	No modification (silent exit)
External	https://example.com/	No modification (silent exit)

Sources: hooks/rewrite-docs-url.test.sh:11-30

Conclusion

Extending the Hook System within claude-code-docs allows for high-efficiency documentation retrieval by transforming high-level user or agent requests into direct links to clean Markdown sources. By leveraging the PreToolUse event and hooks.json configuration, developers can automate permission handling and input sanitization, ensuring that Claude Code interacts with the most relevant and readable version of the project's documentation.