readme-guardian 1.0.0

The README freshness guarantee for vibe coders. Auto-syncs README.md with live data before every push.

🛡️ readme-guardian

The README freshness guarantee for vibe coders.

One command. Zero config. Every push.
Auto-syncs your README with live test counts, API routes, and modules.
Works with every AI agent, every language, every project.

Quick Start • Install • How It Works • The Badge • For AI Agents • CI • Comparison

^{npm install -g readme-guardian • brew install readme-guardian • pipx install readme-guardian}

Metric	Value
Language	python
Version	1.0.0
Tests	—
Lint	—
Docker	no
Monorepo	no
Latest commit	205361a cleanup: remove VS Code extension, update Homebrew install cmd

---

🏅 The Freshness Badge

This is the status symbol of the vibe coding era.

Once you install readme-guardian, your repo gets a readme-badge.svg that updates on every push:

![readme-guardian](./readme-badge.svg)

What it tells the world:

Badge color	Meaning	Trust level
Green	README is fresh, tests pass	✅ High
Yellow	README synced but no tests	⚠️ Medium
Red	README is stale	❌ Low

Why this matters: When a developer visits your repo and sees a green badge, they know instantly:

• The docs are accurate
• Tests were run recently
• This project is actively maintained

When they see a red badge, they know to be cautious. The badge doesn't lie because it's generated from live data on every push.

It's also self-promoting. Every repo with the badge advertises readme-guardian. The more repos use it, the more it becomes the standard for README freshness.

---

🤔 The Problem

You're vibe coding with an AI agent. You ship fast. PRs land. Push to GitHub.

The code is perfect. The README still says "hello world" from day one.

Your project looks abandoned. Contributors bounce. Users leave. Nobody trusts a project with a stale README.

"The README is the first thing people see. If it's wrong, they assume the code is too."

---

🛡️ The Solution

npx readme-guardian --install

That's it. One command. Now before every git push, readme-guardian:

1. 🔍 Detects your stack (Node, Python, Go, Rust — monorepos too)
2. 🧪 Runs your tests and live-counts passes
3. 🗺️ Scans for API routes
4. 📦 Lists source modules and frontend components
5. 📝 Updates the README with verified data
6. ✅ Only if something actually changed

Your README is always accurate. You never think about it.

---

🚀 Quick Start

# Try it right now — no install needed
npx readme-guardian

# Then install for every push
npx readme-guardian --install-hook

📦 Install

Pick your poison:

npm / npx (recommended for JS/TS projects)

# Run without installing (auto-installs Python CLI)
npx readme-guardian

# Install globally
npm install -g readme-guardian
readme-guardian --install-hook

pipx (recommended for Python projects)

pipx install readme-guardian
readme-guardian --install-hook

Homebrew (macOS)

brew install jeevesh2515/homebrew-tap/readme-guardian
readme-guardian --install-hook

Commands

Command	What it does
readme-guardian	Interactive preview — see what would change
readme-guardian --apply	Apply changes immediately
readme-guardian --check	CI mode — exit 1 if README is stale
readme-guardian --install-hook	Install pre-push hook (runs automatically)
readme-guardian --uninstall-hook	Remove the pre-push hook
readme-guardian --version	Show version

---

🧠 How It Works

Zero-config detection

readme-guardian auto-detects your project by looking at your config files:

File	What we learn
package.json	Name, version, scripts, frontend deps, workspaces
pyproject.toml	Name, version, test/lint tooling
go.mod	Module name, test command
Cargo.toml	Name, version, test command

No configuration files. No API keys. No setup.

What we collect

📁 Project root
 ├── Stack type       → Node / Python / Go / Rust
 ├── Test count       → Live from pytest / npm test / go test / cargo test
 ├── API routes       → FastAPI, Express, Next.js App Router, Go Chi/Gin
 ├── Source modules   → Python packages, Node modules, Go packages
 ├── UI components    → React, Vue, Svelte files
 ├── Lint status      → ruff, ESLint
 └── Git state        → Last commit hash and message

What we generate

A clean, beautiful README with:

• Live badges — test count, version, lint status, Docker support
• The freshness badge — ![README](https://img.shields.io/badge/README-fresh-brightgreen) — a status symbol that tells the world your docs are accurate
• Quick start — framework-aware install instructions
• API route table — all detected endpoints with methods
• Module list — source code directory structure
• Component inventory — frontend UI components
• Test suite status — live count, not a hardcoded number

Non-destructive by design

If your README has <!-- readme-guardian:stats --> markers, only content between markers is replaced. Everything else — your narrative, architecture docs, contribution guidelines — stays intact.

If no markers exist, readme-guardian generates a complete README and asks first.

---

🤖 For AI Agents

This repo ships a companion skill file (SKILL.md) that turns any AI coding agent into a documentation partner.

Installation

# Claude Code, OpenCode
cp SKILL.md ~/.agents/skills/readme-guardian/SKILL.md

# Codex CLI
cp SKILL.md ~/.codex/skills/readme-guardian/SKILL.md

# Cursor
# Add SKILL.md to .cursor/skills/

How agents use it

You: "Update the README"
Agent: [runs readme-guardian, reviews diff, adds context about
       the architecture decisions made during this session,
       verifies the freshness badge matches test count]

The CLI handles facts (test counts, routes, versions). The agent handles context (why decisions were made, architectural rationale). Together they produce documentation that's both accurate and insightful.

Compatible with

Claude Code • Codex CLI • OpenCode • Cursor • GitHub Copilot • Continue.dev • Antigravity • Windsurf

---

🔁 CI Enforcement

Add to any GitHub Actions workflow:

# .github/workflows/readme-check.yml
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - run: pip install readme-guardian
      - run: readme-guardian --check

Any PR with a stale README fails automatically. No more merging docs that don't match reality.

---

📊 Comparison

Feature	Manual	CI-only	readme-guardian
Auto-detect project type	❌	❌	✅
Live test count on push	❌	❌	✅
Scan for API routes	❌	❌	✅
List UI components	❌	❌	✅
Pre-push hook (zero effort)	❌	❌	✅
CI enforcement	❌	✅	✅
AI agent companion	❌	❌	✅
Freshness badge	❌	❌	✅
Works offline	✅	❌	✅
Zero config	❌	❌	✅

---

🔐 Security

• Zero network calls. No telemetry, no API keys, no phone home.
• No credential access. Does not read .env, secrets, or config files.
• Reads only source structure. Scans for patterns, not content.
• Suppressed build output. All commands redirect stdout to logs.
• Git-local. Only modifies README.md. Never touches source code.
• Ask-first mode. Interactive mode shows diff before applying.

---

🌟 Why You'll Love It

If you use AI agents, you know the pain: agents ship code at machine speed but documentation stays human-slow. readme-guardian closes the gap. Your README becomes a build artifact — verified at push time, not remembered at documentation time.

If you maintain open source, the freshness badge is a trust signal. Projects with README: fresh attract contributors. Projects with stale READMEs repel them.

If you're a team lead, enforce README freshness in CI. Block PRs with stale docs. Make documentation a first-class citizen.

---

🧰 For Maintainers

.
├── README.md                  # This file — hand-crafted with markers
├── SKILL.md                   # AI agent companion skill
├── pyproject.toml             # Python package (pipx installable)
├── readme_sync/
│   ├── __init__.py            # CLI implementation
│   └── __main__.py            # python -m entry point
├── .github/workflows/         # CI enforcement (copy to your repo)
│   └── readme-check.yml
├── LICENSE                    # MIT
└── .gitignore

---

📜 License

MIT — do whatever you want. Fork it, modify it, use it in proprietary projects, include it in your own AI agent toolchains. Attribution appreciated but not required.

---

_{Built for the vibe coding era.
Documentation shouldn't be an afterthought — it should be a build artifact.
Star this repo. Your future self will thank you.}