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

> Learn to debug awesome-claude-code issues. Use verbose link validator output, check your GITHUB_TOKEN, and inspect resource overrides for effective troubleshooting.

- Repository: [Really Him/awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code)
- Tags: how-to-guide
- Published: 2026-03-24

---

**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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/scripts/utils/github_utils.py)** provides centralized GitHub API wrappers with rate-limit handling and URL parsing.
- **[`scripts/readme/generate_readme.py`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/scripts/readme/generate_readme.py)** consumes the validated CSV to produce styled README variants (awesome, flat, extra, classic).
- **[`templates/resource-overrides.yaml`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/templates/resource-overrides.yaml)** locks specific fields for individual resources to prevent automated overwrites.
- **[`acc-config.yaml`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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:

```bash
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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/github_utils.py)) correctly handles the repository structure.

### Unexpected CSV Changes

If fields revert unexpectedly after manual edits, examine [`templates/resource-overrides.yaml`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/templates/resource-overrides.yaml). This file locks specific fields under resource IDs, and the `apply_overrides` function (lines 93-126 of [`validate_links.py`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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:

```bash
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:**
  ```bash
  python -m scripts.validation.validate_links --verbose
  ```

- **Ignore overrides to see raw validation state:**
  ```bash
  python -m scripts.validation.validate_links --ignore-overrides
  ```

- **Limit to first 10 links for quick iteration:**
  ```bash
  python -m scripts.validation.validate_links --max-links 10
  ```

- **Check GitHub rate-limit status independently:**
  ```bash
  curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit
  ```

- **Test GitHub URL parsing for a specific resource:**
  ```python
  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:

```bash
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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/validate_links.py)).

### Manually Fetching Repository Metadata

Test GitHub API interaction for a single repository:

```python
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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/templates/resource-overrides.yaml) to freeze specific fields:

```yaml
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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/acc-config.yaml):

```bash
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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/github_utils.py) functions to narrow down failures.
- **Verify the pipeline:** After CSV fixes, run [`generate_readme.py`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/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`](https://github.com/hesreallyhim/awesome-claude-code/blob/main/templates/resource-overrides.yaml).