Open-source project
Cog-Creators/Red-Index avatar
Cog-Creators/Red-Index

Red-Index: A Scheduled Indexer for Red Discord Bot Repositories

Auto-indexer of repositories and cogs

37 stars77 forksPythonGPL-3.0

At a glance

What is it?
Red-Index is a GitHub Actions-driven tool that compiles a JSON index of Red bot cogs and repositories every 15 minutes. It is the data source behind index.discord.red and the Index cog, and it is straightforward to fork for your own use.
Who is it for?
Adopt Red-Index if you run a service that needs a current list of Red bot cogs and repositories, or if you want to maintain a private index for a curated set of repos. Do not use it if you need real-time updates, since the 15-minute schedule and GitHub Actions dependency introduce delay.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Cog-Creators/Red-Index37 ★ · +1
Star history
Repository2026-08-212026-11-15
Cog-Creators/Red-Index3637

1 Stars in the last 86 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What Red-Index Solves and Who It Targets

Red-Index addresses a specific discovery problem for the Red Discord bot ecosystem. Red allows users to install third-party cogs, which are plugins hosted in separate repositories. Finding these repositories and keeping track of their metadata, such as author, description, and available cogs, is a manual task. Red-Index automates this by periodically cloning every listed repository and generating a structured index. The target audience is not the average Red user but developers who build services around Red, such as web interfaces or in-bot search tools. The README explicitly names two consumers: index.discord.red, a web interface, and the Index cog, which lets users search and install directly from their Red instance. If you are building a third service, the project's stated purpose is to serve as a source for you.

The Mechanism: GitHub Actions and a YAML Source List

The core mechanism is a GitHub Actions workflow. According to the README, the workflow runs every 15 minutes or on a manual trigger. It parses a repositories list, clones each repository, and compiles a JSON file with current metadata for each repository and cog. The source list lives in repositories.yaml, with repositories-example.yaml showing the expected structure. The output is committed back to the repository under the index directory. A key design choice is the minified version, 1-min.json, and its gzip counterpart, 1-min.json.gz. The version number in the filename is a contract: the README states that substantial changes to the data format will increase the version number and change the link. This gives downstream consumers a stable URL to fetch, as long as they pin to a version. The workflow's reliance on GitHub Actions means the index is only as fresh as the last successful run, and any failure in the action pipeline would stall updates.

Getting It Running: Fork, Edit, Enable

The README gives a concise runbook for running your own instance. Fork the project, edit the repositories list, enable the actions, and it will work. There are no installation commands beyond that. The repositories-example.yaml file is the template for compiling the list. You need to specify which repositories to index, presumably with URLs and maybe additional metadata, though the README does not detail the exact fields. The workflow is already defined in the repository, so enabling Actions on your fork is the main step. You do not need to run Python locally, because the indexing logic executes inside GitHub Actions. This makes deployment nearly zero-cost if you already use GitHub. However, it also means you are bound to GitHub's infrastructure and its scheduling limits. The 15-minute interval is fixed; you cannot change it without editing the workflow file, which the README does not explain.

A Genuine Limitation: The Unapproved Category and Manual Review

Red-Index has a built-in distinction between approved and unapproved repositories. The README explains that to get a repo into the approved category, you must apply through a Cog Creator application. Until approval, you can make a pull request to have the repo added to the unapproved category. This is a moderation gate, not a technical one. For someone running their own index, this distinction is irrelevant because you control the repositories list. But for the public index, it means the data is not exhaustive. Some repos are present but marked as unapproved, and the criteria for approval are not technical. If you build a service on top of the public index, you inherit this categorization, and users may see a two-tier list. The README does not say whether the JSON includes an approval flag, but the existence of the categories implies it must. This is a real limitation: the index reflects the maintainers' review process, not just raw availability.

The Wrong Tool for Real-Time or High-Frequency Use

Red-Index is a batch indexer with a 15-minute cadence. That makes it unsuitable for any use case that needs immediate updates, such as a service that must reflect a newly pushed cog within seconds. The index is a snapshot, not a live feed. If you run your own fork, the schedule is still the same unless you modify the workflow. Also, the index is committed to a git repository, which means each update creates a commit. Over time, this grows the repository history, though the README does not mention any cleanup mechanism. For a small list of repos, this is fine, but for a large list, the repository size could become unwieldy. The gzip version mitigates download size for consumers, but not the storage cost on the index side. If you need a different update frequency or a push-based model, Red-Index is not the right fit.

Alternatives: Rolling Your Own vs. Using the Existing Services

The obvious alternative is to not run Red-Index at all and instead consume the existing public index directly. The README encourages this: fetch the minified JSON or gzip from the raw GitHub URL and parse it. This is simpler and requires no infrastructure. The difference is control. Using the public index means you depend on the maintainers' repository list and their approval process. Running your own fork gives you control over the list, but you must maintain it and handle the Actions workflow yourself. Another alternative is to write a custom scraper that hits GitHub APIs directly to list Red cogs, but that would miss the structured metadata that Red-Index provides, such as cog descriptions and authors. The README does not mention any official API, so the JSON file is the only interface. The trade-off is between convenience and independence.

Maintenance, Upgrade Cost, and License Implications

The maintenance cost is low for a consumer: you just fetch a static file. For a self-hosted fork, the cost is in keeping the repositories.yaml list current and monitoring the GitHub Actions runs. The README does not document any versioning strategy beyond the filename version number. If the data format changes, the link changes, so you must update your parser. The project is licensed under GPL-3.0. This is a copyleft license, which means if you distribute a modified version of Red-Index, you must release your changes under the same license. For a service that merely consumes the JSON output, the license may not apply to your code, but if you fork and alter the indexing logic, it does. The README does not provide a changelog or release history, so you cannot easily track changes. You must watch the repository for updates to the workflow or the example YAML.

Editorial conclusion

Adopt Red-Index if you run a service that needs a current list of Red bot cogs and repositories, or if you want to maintain a private index for a curated set of repos. Do not use it if you need real-time updates, since the 15-minute schedule and GitHub Actions dependency introduce delay. Before adopting, verify the repositories.yaml format, test a fork with a small list, and confirm that the minified JSON schema (currently version 1) meets your parsing needs. The project is GPL-3.0 licensed, so check that your service's license is compatible if you redistribute modified versions.

Frequently asked questions

What is Red-Index?

It is an auto-indexer of repositories and cogs for the Red Discord bot. A GitHub Actions workflow runs every 15 minutes or on manual trigger, parses the repositories listed in repositories.yaml, clones each one and compiles a JSON file with their current metadata, served from the index directory of the repository.

What does it mean if my red blood cell indices are normal?

This repository has nothing to do with blood counts. Red-Index is a scheduled GitHub Actions job for the Red Discord bot that clones each listed repository and compiles a JSON index of their metadata every 15 minutes.

Which animals are endangered according to the IUCN, as listed here?

The repository contains no conservation data. It publishes a JSON index of Discord bot repositories and cogs, which services consume as a minified file, index/1-min.json, or its gzip equivalent, and which is regenerated every 15 minutes.

How do I calculate an RBC index, and is that what this repo does?

No calculation is involved. The repository runs parser and indexer scripts against a YAML list of repositories, and its only runtime dependency is pyyaml. Its licensing is GPL-3.0 and it ships no releases, so it is best read as a continuously regenerated data feed rather than a library you install.

Official sources

  1. Official README
  2. Project repository
  3. README
  4. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/cog-creators-red-index.svg)](https://hysenlabs.com/projects/cog-creators-red-index)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/cog-creators-red-index.svg)](https://hysenlabs.com/projects/cog-creators-red-index)

Was this useful?