RedRing Documentation

Comprehensive guide to context-first developer diagnostics, scanner architecture, CLI usage, and extension specifications.

v0.2.0-alpha.2 (Active Dev) CLI Core MIT Open Source
Quick Jump: ⚡ Installation 🚀 Quick Start 📦 Tech Stack 🏗️ Architecture 🔬 Scanner Spec 🗺️ Roadmap
Active Dev Status

Engine Version v0.2.0-alpha.2

RedRing is under active development. Today it ships as a high-performance CLI engine with working scanners for Python, Git, and Docker. Other ecosystem toolchains are tracked in the Roadmap.

What is RedRing?

RedRing is an evidence-driven developer diagnostics platform that helps developers identify and resolve environment-specific issues. The product is built around the fundamental core principle that diagnostic tools should inspect the local developer environment before producing recommendations.

Instead of assuming or guessing, RedRing gathers system context, runs stack-specific scanners, and then reasons over the normalized evidence to provide grounded, practical guidance.

Why RedRing?

Most developer troubleshooting tools assume they already know your environment state. RedRing takes a different approach by verifying the actual runtime state first before making recommendations.

Evidence-First Diagnosis

Collect and normalize environment facts before arriving at any diagnostic conclusion. Zero blind assumptions.

Developer-Centric Guidance

Delivers actionable, human-readable terminal insights designed to speed up real-world debugging workflows.

Explainable AI Layer

Optional AI integration reasons strictly over verified system state—it explains facts, never invents them.

Modular Architecture

Self-registering scanner plugins enable straightforward stack expansion without modifying core engine logic.

Supported Tech Stack

RedRing's current v0.2.0-alpha.2 build focuses on three major developer toolchains with fully active scanners.

Available Now

LIVE & SHIPPED
  • Python — interpreter check, active virtual environment, pip health, and PATH conflict detection.
  • Git — version sanity, global config check (user.name/email), and credential helper validation.
  • Docker — daemon status, engine version, virtualization support (VT-x/AMD-V), and socket checks.
python.version git.config docker.daemon

Planned Ecosystems

UPCOMING

Toolchain scanners scheduled in the roadmap:

Node.js Java Rust Go PostgreSQL Redis MongoDB Kubernetes Flutter

Installation

The easiest way to install RedRing is via Python's package manager. The package is published on PyPI and installs cleanly with one command:

bash
$ pip install redring

This installs the redring CLI executable into your PATH. Verify the installation by running redring version.

Quick Start

RedRing's core diagnostic command is diagnose followed by the stack target. Zero preliminary setup required.

bash
$ redring diagnose docker

Swap docker for python or git to inspect other installed environments.

First Diagnosis

When executing a diagnosis, every registered scanner under that target collects empirical evidence from your local machine and outputs a structured result block:

bash
$ redring diagnose python Python Version ----------------------------------- Status: ✔ PASS ----------------------------------- Evidence: • Version : 3.12.3 • Command : python -----------------------------------

A FAIL or WARNING status details the raw evidence that caused it. Append --with-ai to attach LLM-powered context summaries.

AI-Based Explanations

Optional. Core scanner evidence collection works 100% offline with zero API keys required. You can optionally enable AI to synthesize multi-scanner findings into cohesive explanations.

Supported LLM Providers

Bring your existing API key from Groq, OpenAI, Anthropic Claude, or Google Gemini.

Architecture

The RedRing engine separates evidence gathering from presentation layers through a decoupled pipeline architecture.

CLI / API
➔
Engine
➔
ScannerRegistry
➔
Scanners
➔
ScanResults
➔
Renderer

Core Components

  • Entry Points — CLI (Typer) and future Web/Desktop interfaces.
  • Engine — Coordinates scanner execution for requested stacks.
  • ScannerRegistry — Auto-discovers scanners dynamically upon module import.
  • Scanners — Single-responsibility inspection units returning ScanResult dataclasses.
  • Renderers — Format final output into terminal tables, JSON, or UI views.

Scanner Specification

A scanner is an isolated component responsible for collecting exactly one piece of environment data.

Single Responsibility

One scanner checks one exact capability.

Read-Only

Never mutates system configuration.

Zero-AI

Collects facts; no subjective reasoning.

Structured

Returns typed dataclass objects.

Output Schema

capability: "python.version" status: ScanStatus.PASS evidence: version: "3.12.3" command: "python" warnings: [] errors: []

Roadmap

Development milestones guiding RedRing towards full platform availability.

Phase 1 — Core Foundation

Current Release (v0.2.0-alpha.2)

Architecture definition, scanner framework, evidence engine, and initial Python, Git, and Docker scanners.

Phase 2 — Web & JS Ecosystem

Planned

Toolchain checks for Node.js, npm, pnpm, yarn, and frontend build bundlers.

Phase 3 — Database Services & Infra

Planned

Service discovery for PostgreSQL, MySQL, Redis, MongoDB, and WSL/VM diagnostics.

Phase 4 — Mobile & Plugin SDK

Planned

Flutter/Android environment inspection and community third-party scanner plugin API.

Contributing

RedRing is open source under the MIT License. We welcome community scanners, documentation updates, and bug fixes!

View Contributing Guidelines on GitHub