Shell Script URL Rewriting
Relevant source files
The following files were used as context for generating this wiki page:
The Shell Script URL Rewriting system is a specialized component of the claude-code-docs project designed to intercept and modify WebFetch tool calls within the Claude Code environment. Its primary purpose is to transform standard HTML documentation URLs from code.claude.com/docs into their corresponding .md (Markdown) source twins. This ensures that the AI agent receives clean, structured Markdown content instead of an HTML application shell, leading to more token-efficient and accurate documentation parsing.
Sources: hooks/hooks.json:2-3, hooks/rewrite-docs-url.sh:2-5, README.md:65-69
Hook Architecture and Execution
The rewriting logic is implemented as a PreToolUse hook. It is configured to trigger specifically when the WebFetch tool is invoked. The hook executes a Bash script that processes the tool's input, performs validation and string manipulation, and returns a JSON response that Claude Code uses to proceed with the modified request.
Integration Pipeline
The following sequence diagram illustrates how the hook intercepts a documentation request before it reaches the external network.
The hook returns an updatedInput object with a permissionDecision set to "allow", which permits the rewritten fetch to proceed without requiring additional user confirmation.
Sources: hooks/hooks.json:5-13, hooks/rewrite-docs-url.sh:31-39, README.md:76-78
Logic and Filtering Rules
The rewrite script (rewrite-docs-url.sh) employs several layers of filtering to ensure only appropriate documentation pages are transformed.
URL Transformation Logic
- Domain Matching: The script only acts on URLs starting with
https://code.claude.com/docs/. - Fragment and Query Removal: It strips URL fragments (starting with
#) and query parameters (starting with?) to reach a clean base path. - Extension Checking: If a URL already contains a file extension (e.g.,
.md,.txt,.png), it is ignored to prevent double-extension errors or breaking asset fetches. - Locale Validation: The script ensures the path contains a locale segment (e.g.,
/docs/en/page) and does not attempt to rewrite the root documentation directory.
Sources: hooks/rewrite-docs-url.sh:11-30
Transformation Examples
| Input URL Type | Resulting Behavior |
|---|---|
| Standard Doc Page | Appends .md (e.g., /en/agents -> /en/agents.md) |
| URL with Fragment | Strips fragment, appends .md |
| Already Markdown | Silent exit (No change) |
| Non-Docs Domain | Silent exit (No change) |
| Docs Root | Silent exit (No change) |
Sources: hooks/rewrite-docs-url.sh:11-30, README.md:71-74, hooks/rewrite-docs-url.test.sh:19-28
Implementation Details
Hook Configuration
The hook is registered in hooks/hooks.json, defining the command path and a 5-second timeout.
{
"matcher": "WebFetch",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/rewrite-docs-url.sh",
"timeout": 5
}
]
}
Sources: hooks/hooks.json:6-14
Data Processing with jq
The shell script heavily utilizes jq to parse the incoming JSON stream from stdin and to construct the outgoing JSON response. It specifically targets the .tool_input.url field.
input=$(cat)
url=$(jq -r '.tool_input.url // empty' <<<"$input")
# ... processing ...
jq --arg url "${path}.md" '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "allow",
permissionDecisionReason: ("Rewrote Claude Code docs URL to markdown source: " + $url),
updatedInput: (.tool_input | .url = $url)
}
}' <<<"$input"
Sources: hooks/rewrite-docs-url.sh:8-9, hooks/rewrite-docs-url.sh:31-39
Testing and Validation
The project includes a comprehensive test suite in hooks/rewrite-docs-url.test.sh that validates the transformation logic against various edge cases.
Test Categories
- Rewrite Tests: Ensures valid documentation paths are correctly appended with
.md. - Silent Tests: Confirms that URLs that should not be touched (like images, the
llms.txtmanifest, or external domains) result in no output, allowing the original tool call to proceed normally. - Payload Integrity: Verifies that other tool inputs, such as a
promptfield, are preserved in theupdatedInputobject during the rewrite process.
Sources: hooks/rewrite-docs-url.test.sh:19-33
Summary
Shell Script URL Rewriting provides a transparent optimization layer for the Claude Code documentation plugin. By converting HTML-bound URLs to Markdown sources via a PreToolUse hook, the system ensures that AI agents interact with the most structured and concise version of the documentation. This mechanism is governed by strict filtering rules to maintain compatibility with assets, manifests, and non-documentation URLs.
Sources: README.md:65-69, hooks/rewrite-docs-url.sh:2-5