Troubleshooting Dependencies
Relevant source files
The following files were used as context for generating this wiki page:
Troubleshooting dependencies in the claude-code-docs project involves managing and verifying the tools required to sync, search, and serve the Claude Code documentation mirror. The project relies on external CLIs such as ask and csp, as well as runtime environments like Bun and Node.js to maintain a local, version-pinned copy of official documentation.
Effective troubleshooting ensures that the documentation remains accessible to AI coding agents even when primary tools are missing or network conditions are restrictive. This is achieved through defined fallback mechanisms, such as switching from semantic search to grep or from the ask CLI to direct WebFetch operations.
Sources: README.md:1-25, skills/claude-code-docs/SKILL.md:1-20
CLI Tooling and Path Resolution
The project utilizes two primary CLI tools: ask (Agent Skills Kit) and csp (Code Search Please). Troubleshooting often begins with verifying if these are on the system PATH.
Dependency Fallback Logic
When a tool is not found on the PATH, the system is designed to fall back to npx or bunx to run the latest version from the npm registry. If registry access is also unavailable (e.g., in offline sandboxes), the system falls back to standard Unix utilities like grep.
The diagram shows the hierarchical fallback strategy for resolving tools and searching documentation.
Sources: skills/claude-code-docs/SKILL.md:21-50, README.md:27-50
Resolution Commands
| Tool | Primary Command | Fallback Command | Purpose |
|---|---|---|---|
ask | ask src <repo> | npx -y @pleaseai/ask src <repo> | Resolves cached checkout path |
csp | csp search <q> | npx -y @pleaseai/csp search <q> | Semantic search over markdown |
sync | bun sync.ts | N/A | Rebuilds local docs/ from manifest |
Sources: skills/claude-code-docs/SKILL.md:23-45, sync.ts:1-10
Synchronization Failures
The sync.ts script treats llms.txt as the source of truth for all mirrored documentation. Failures in this module typically stem from network issues or manifest corruption.
Network and Fetch Errors
The synchronization process implements a retry mechanism to handle transient network errors. It attempts to fetch resources up to 3 times with exponential backoff. If all attempts fail, the script throws an error and aborts the run to prevent committing a partial or broken tree to the repository.
const RETRIES = 3;
async function fetchText(url: string): Promise<string> {
for (let attempt = 1; attempt <= RETRIES; attempt++) {
try {
const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status} on ${url}`);
return await res.text();
} catch (error) {
if (attempt < RETRIES) await Bun.sleep(1000 * attempt);
}
}
}
Sources: sync.ts:38-52
Manifest Integrity Checks
To prevent mass deletions caused by a broken manifest parse, the script enforces a minimum page count. If fewer than 10 pages are identified in the manifest, the process fails immediately.
Sources: sync.ts:54-61
Hook and Plugin Troubleshooting
The Claude Code plugin uses a PreToolUse hook to intercept WebFetch calls. Issues here usually manifest as Claude reading HTML app shells instead of raw markdown.
Hook Execution Flow
The hook executes a bash script (rewrite-docs-url.sh) that uses jq to manipulate the tool input. Troubleshooting requires ensuring bash and jq are available in the execution environment.
The sequence shows how the hook intercepts a fetch request to rewrite URLs to their .md source.
Sources: hooks/hooks.json:1-15, hooks/rewrite-docs-url.sh:1-10
Testing Rewrites
The project includes a test suite (hooks/rewrite-docs-url.test.sh) to validate URL rewriting logic. This is the primary tool for troubleshooting regex or path-parsing failures.
| Input URL | Expected Troubleshooting Outcome |
|---|---|
.../docs/en/agents | Should append .md |
.../docs/en/hooks#anchor | Should strip anchor and append .md |
.../docs/llms.txt | Should be ignored (silent exit) |
https://example.com | Should be ignored (outside domain) |
Sources: hooks/rewrite-docs-url.test.sh:15-30
Summary
Troubleshooting dependencies in claude-code-docs focuses on the availability of the ask and csp CLIs and the reliability of the sync.ts script. The system is designed to be resilient, providing npx fallbacks for missing binaries and retry logic for network-dependent sync operations. Verification of these dependencies can be performed through the provided test scripts and by monitoring GitHub Action logs for sync aborts.