How to Debug Issues in the awesome-claude-code Project: A Complete Troubleshooting Guide

Debug issues in the awesome-claude-code project by running the link validator with --verbose to expose raw GitHub API responses, ensuring your GITHUB_TOKEN environment variable is configured, and inspecting field-locking overrides in templates/resource-overrides.yaml that prevent CSV updates.

The awesome-claude-code repository automates curation of Claude Code resources through a Python toolkit that validates links and generates documentation. Debugging this project requires navigating its CSV-based data store and validation scripts. This guide provides exact diagnostic steps using the repository's source code.

Core Architecture Overview

The project consists of interconnected components that process THE_RESOURCES_TABLE.csv as the single source of truth.

• THE_RESOURCES_TABLE.csv stores every tool with metadata including links, license, status, and staleness flags.
• scripts/validation/validate_links.py walks the CSV, checks URLs, and updates the Active, Last Checked, Last Modified, and Stale columns.
• scripts/utils/github_utils.py provides centralized GitHub API wrappers with rate-limit handling and URL parsing.
• scripts/readme/generate_readme.py consumes the validated CSV to produce styled README variants (awesome, flat, extra, classic).
• templates/resource-overrides.yaml locks specific fields for individual resources to prevent automated overwrites.
• acc-config.yaml controls which README style serves as the repository root.

The validator is the most frequently executed component in CI pipelines, making it the primary surface where bugs manifest.

Common Failure Modes and Diagnostic Steps

All Resources Marked Inactive Due to Rate Limiting

When every resource shows Active as FALSE, the likely cause is a missing or expired GITHUB_TOKEN. Without authentication, GitHub API calls return 403 rate-limit errors.

Run the validator with diagnostic output to confirm:

python -m scripts.validation.validate_links --verbose

Look for "GitHub rate limit hit" messages in the output. The script requires a valid token for license checks and last-modified date retrieval.

License Column Remains Empty

Empty license fields indicate github_request_json in scripts/utils/github_utils.py (lines 46-68) is failing to parse the API response, or the target repository lacks a license file.

Enable --verbose mode to inspect the raw JSON payload returned by the GitHub API. The function parses this response to extract the spdx_id field.

Stale Flag Never Updates

The Stale flag depends on the Last Modified date retrieved by get_github_last_modified. If this function receives a repository URL without a specific file path, it cannot determine the last commit date and returns None.

Verify that URLs in the CSV point to specific files when necessary, or check that the path extraction logic in parse_github_url (lines 70-118 of github_utils.py) correctly handles the repository structure.

Unexpected CSV Changes

If fields revert unexpectedly after manual edits, examine templates/resource-overrides.yaml. This file locks specific fields under resource IDs, and the apply_overrides function (lines 93-126 of validate_links.py) enforces these locks during validation.

Check which fields are listed under each resource ID in the overrides file. Locked fields persist regardless of what the validator discovers.

Network Timeouts in URL Validation

Random requests timeouts occur in the validate_url function's retry loop (lines 75-92 of validate_links.py). The implementation uses exponential back-off that doubles with each attempt.

If network hiccups persist, increase the initial timeout value or adjust the retry logic in the validation script.

Step-by-Step Debugging Workflow

1. Run the Validator Locally

Reproduce CI behavior with detailed diagnostics:

python -m scripts.validation.validate_links --verbose

The --verbose flag activates the if VERBOSE: block around line 85, dumping raw GitHub API responses to stdout. This reveals exactly what data the CSV receives.

2. Verify Environment Variables

Confirm the GitHub token is present:

echo "Token present? ${GITHUB_TOKEN:+yes}"

Without this token, the script validates plain HTTP URLs but fails GitHub-specific checks for licenses and modification dates.

3. Inspect Field Overrides

Search for locked fields affecting specific resources:

grep -A3 -B1 "<resource-id>" templates/resource-overrides.yaml

Locked fields under each ID prevent the validator from updating those columns, even when new data is available.

4. Isolate Single Row Issues

Test problematic entries in isolation:

head -n 2 THE_RESOURCES_TABLE.csv > mini.csv
python -m scripts.validation.validate_links mini.csv

This keeps only the header plus one data row, enabling rapid iteration without processing the entire table.

5. Review GitHub Request Helpers

The core API interaction lives in scripts/utils/github_utils.py:

• github_request_json (lines 46-68) returns status codes, headers, and parsed JSON
• parse_github_url (lines 70-118) determines if a URL can become a content API endpoint

Inspect these functions when GitHub-specific data appears incorrect.

6. Validate README Generation

After fixing CSV data, ensure the documentation builds correctly:

python -m scripts.readme.generate_readme

Errors here typically indicate missing badge assets in the assets/ directory or malformed markdown content in the CSV fields.

Essential Debug Commands

Use these commands for specific diagnostic goals:

• Run full validation with maximum visibility:

  python -m scripts.validation.validate_links --verbose

• Ignore overrides to see raw validation state:

  python -m scripts.validation.validate_links --ignore-overrides

• Limit to first 10 links for quick iteration:

  python -m scripts.validation.validate_links --max-links 10

• Check GitHub rate-limit status independently:

  curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit

• Test GitHub URL parsing for a specific resource:

  python -c "from scripts.utils.github_utils import parse_github_url; print(parse_github_url('https://github.com/owner/repo'))"

Practical Debugging Examples

Running CI-Style Validation Locally

Install dependencies and execute the full validation suite:

pip install -r requirements.txt
python -m scripts.validation.validate_links --verbose

The script writes results back to THE_RESOURCES_TABLE.csv and prints a JSON summary (lines 88-94 of validate_links.py).

Manually Fetching Repository Metadata

Test GitHub API interaction for a single repository:

from scripts.utils.github_utils import github_request_json, parse_github_url

url = "https://github.com/avifenesh/agentsys"
api_url, is_github, owner, repo = parse_github_url(url)

if is_github:
    status, _, data = github_request_json(api_url)
    if status == 200:
        licence = data.get("license", {}).get("spdx_id", "UNKNOWN")
        print(f"{owner}/{repo} licence: {licence}")

This isolates whether the issue lies in URL parsing or API response handling.

Locking a Resource to Prevent Updates

Create or modify templates/resource-overrides.yaml to freeze specific fields:

overrides:
  abc123:
    active: "FALSE"
    skip_validation: true
    notes: "Deprecated tool"

Run with --ignore-overrides to bypass these locks during testing.

Generating Alternative README Styles

Test specific output formats defined in acc-config.yaml:

python -m scripts.readme.generate_readme --style flat

The script selects the appropriate markup module from scripts/readme/markup/ based on the style argument.

Summary

• Start with the validator: Most issues surface in scripts/validation/validate_links.py, particularly when processing THE_RESOURCES_TABLE.csv.
• Use --verbose mode: This exposes raw GitHub API traffic and reveals whether GITHUB_TOKEN authentication is working.
• Check overrides: templates/resource-overrides.yaml can lock fields and prevent expected CSV updates via the apply_overrides function.
• Isolate problems: Test single rows or manual API calls using github_utils.py functions to narrow down failures.
• Verify the pipeline: After CSV fixes, run generate_readme.py to ensure documentation renders correctly.

Frequently Asked Questions

Why are all resources showing as inactive?

This occurs when the GITHUB_TOKEN environment variable is missing, expired, or lacks permissions. The validator relies on this token for GitHub API calls; without it, rate limiting (403 errors) causes all GitHub URLs to fail validation. Run the validator with --verbose to confirm "GitHub rate limit hit" messages appear in the output.

How do I check if my GitHub token is working correctly?

Execute the validator with the --verbose flag and inspect the raw API responses printed to stdout. Alternatively, test the token directly with curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit. If this returns valid JSON with rate limit data, the token is functional.

Why isn't the Last Modified date updating for some repositories?

The get_github_last_modified function requires a specific file path to retrieve commit history. If the CSV contains a bare repository URL without a path to a specific file, the function returns None and the Stale flag calculation fails. Ensure URLs include paths to tracked files, or verify that parse_github_url (lines 70-118 of github_utils.py) correctly handles the repository structure.

How do I temporarily ignore overrides to see the raw validation state?

Run the validator with the --ignore-overrides flag: python -m scripts.validation.validate_links --ignore-overrides. This bypasses the apply_overrides logic (lines 93-126) and shows exactly what the validation logic discovers without field-locking interference from templates/resource-overrides.yaml.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}