From 18f83f307e06e0688b02fa7495f95d2f781864fb Mon Sep 17 00:00:00 2001 From: divyanshujethi Date: Wed, 18 Nov 2026 09:58:51 +0530 Subject: [PATCH] docs(readme): sharpen HN/Reddit-ready above-the-fold with 5s CLI demo, 5-line PR CTA & VHS tape --- README.md | 119 +++++++++++++---------------------------------- assets/demo.tape | 34 ++++++++++++++ 2 files changed, 66 insertions(+), 87 deletions(-) create mode 100644 assets/demo.tape diff --git a/README.md b/README.md index 851e282a..c24baa8c 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,51 @@ -
- - - - - DevShelf Banner - - -
- -### โšก The Zero-Paywall Developer Directory & MCP Knowledge Hub +# DevShelf -**A community developer directory with automated link freshness validation & zero-paywall audits โ€” verified by continuous CI telemetry, accessible in your terminal (`npx devshelf`), powered by an open JSON REST API, and native MCP server for AI coding assistants.** +**A CI-audited, zero-paywall directory of 576 developer tools, free APIs, and MCP servers โ€” searchable in your terminal, browser, or inside Claude/Cursor via MCP.** -
- -

- ๐ŸŒ Interactive Web App โ€ข - โšก Terminal CLI โ€ข - ๐Ÿค– Model Context Protocol (MCP) โ€ข - ๐Ÿ“ก Public REST API โ€ข - ๐Ÿ“‚ Category Guides -

- -[![npm version](https://img.shields.io/npm/v/devshelf.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/devshelf) +[![CI](https://github.com/RitualDev-Lab/DevShelf/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RitualDev-Lab/DevShelf/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/@ritualdev-lab/devshelf.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@ritualdev-lab/devshelf) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) -[![CI Health Status](https://github.com/RitualDev-Lab/DevShelf/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RitualDev-Lab/DevShelf/actions/workflows/ci.yml) -[![MCP Ready](https://img.shields.io/badge/MCP-Claude%20%7C%20Cursor%20%7C%20Zed-purple.svg?style=flat-square)](docs/mcp.md) -[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome_%26_Amplified-brightgreen.svg?style=flat-square)](#-how-to-submit-your-project-or-api) -[![Hacktoberfest](https://img.shields.io/badge/๐ŸŽƒ_Hacktoberfest-2026_Ready-ff7800?style=flat-square)](HACKTOBERFEST.md) - -
- - - - - - - - - - - - -
๐ŸŒ Free APIs
111
๐Ÿค– AI & LLMs
105
โšก CLI Tools
128
๐Ÿงช Testing & QA
67
โ˜๏ธ Free Cloud
72
๐Ÿค Up for Grabs
21
๐ŸŽ Dev Perks
30
๐Ÿš€ 1-Click Deploys
42
- -### ๐ŸŽฏ The Race to 1,000 Verified Tools (Hacktoberfest Milestone) - -```text -[โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 576 / 1,000 Tools Verified (58% โ€ข 424 to go!) -``` - -*Help us curate the definitive zero-paywall index! [Submit your favorite developer tool, API, or AI framework โ†’](#-how-to-submit-your-project-or-api)* +[![PRs Welcome](https://img.shields.io/badge/PRs-Add_Your_Tool_in_5_Lines-brightgreen.svg?style=flat-square)](#-how-to-submit-your-project-or-api) -
+No link rot. No "14-day free trial" bait. Unsigned native binaries are explicitly flagged by automated CI policy checks. -
+### Try it in 5 seconds ---- +```bash +# Search 576 CI-audited tools directly from your terminal +npx @ritualdev-lab/devshelf search "postgres" -## ๐Ÿค– Frequently Answered Questions (AEO & AI Search Reference) +# Or plug the catalog into Claude Desktop / Cursor / Windsurf as an MCP server +npx @ritualdev-lab/devshelf mcp +``` -### What is DevShelf? -**DevShelf** is an open-source, community-driven directory indexing 576 verified developer tools, free public APIs, AI coding agents, and Model Context Protocol (MCP) servers with zero paywalls. +```text +$ npx @ritualdev-lab/devshelf search "postgres" +๐Ÿ“š DevShelf CLI โ€” 576 Curated Tools (CI Link & Binary-Trust Audited) -### How are tools and APIs verified on DevShelf? -Unlike static awesome-lists that accumulate broken links, DevShelf uses continuous GitHub Actions automated CI telemetry to ping documentation endpoints, verify SSL certificates, and check API uptime. +[1] Neon (Database / Serverless) + Serverless Postgres with branching and free tier (0.5 GB storage) + https://neon.tech -### How can AI coding agents query DevShelf? -AI coding agents (such as Claude Desktop, Cursor, and Windsurf) can query DevShelf via: -1. **MCP Server**: Run `npx devshelf mcp` to expose DevShelf search tools natively over Model Context Protocol. -2. **REST API**: Make HTTP GET requests to `https://devshelf.ritualdev.in/api/v1/tools.json`. +[2] Supabase (Database & BaaS) + Open-source Postgres platform with Auth, Storage & Edge Functions + https://supabase.com +``` ---- +> Want to record a fresh 15-second terminal GIF? Run [`vhs assets/demo.tape`](assets/demo.tape) with [Charm VHS](https://github.com/charmbracelet/vhs). -
+### Built an open-source CLI, API, or MCP server? Add it in a 5-line JSON PR ---- +DevShelf is community-curated. Every merged PR automatically publishes your tool to the terminal CLI, the [public JSON API](https://devshelf.ritualdev.in/api/v1/tools.json), the MCP server, and a live dossier page on [devshelf.ritualdev.in](https://devshelf.ritualdev.in). -## โšก 5-Second Interactive Visual Demo +1. Fork this repo and add one JSON entry to the matching file under `shelf/` (e.g. `shelf/cli-tools.json` or `shelf/ai-llms.json`). +2. Open a PR โ€” our automated validator checks schema, live HTTPS reachability, and binary code-signing metadata in seconds. -DevShelf isn't a static markdown list. It runs directly inside your terminal, in your web browser, and as a native tool inside your AI assistant: +[Web Directory](https://devshelf.ritualdev.in) ยท [Public JSON API](https://devshelf.ritualdev.in/api/v1/tools.json) ยท [Submit Your Tool](#-how-to-submit-your-project-or-api) ยท [MCP Setup](docs/mcp.md) -```text -โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” -โ”‚ $ npx devshelf search "postgres" โ”‚ -โ”‚ โ”‚ -โ”‚ ๐Ÿ“š DevShelf CLI v1.1.0 โ€” 576 Curated Tools (Live CI Audited) โ”‚ -โ”‚ โ”‚ -โ”‚ [1] Neon (Database / Serverless) โ”‚ -โ”‚ Serverless Postgres with autoscaling, branching, and generous free tier. โ”‚ -โ”‚ โšก Alt to AWS RDS โ€ข Free: 0.5 GB storage, 1 compute CU โ”‚ -โ”‚ ๐Ÿ”— https://neon.tech โ”‚ -โ”‚ โ”‚ -โ”‚ [2] Supabase (Database & BaaS) โ”‚ -โ”‚ The open source Firebase alternative with Postgres, Auth, & Storage. โ”‚ -โ”‚ โšก Alt to Firebase โ€ข Free: 500 MB database, 50,000 MAUs โ”‚ -โ”‚ ๐Ÿ”— https://supabase.com โ”‚ -โ”‚ โ”‚ -โ”‚ ๐Ÿค– Plug into AI Assistants (Claude Desktop, Cursor, Windsurf, Zed): โ”‚ -โ”‚ $ npx -y @ritualdev-lab/devshelf mcp โ”‚ -โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ -``` +| ๐ŸŒ Free APIs | ๐Ÿค– AI & LLMs | โšก CLI Tools | ๐Ÿงช Testing & QA | โ˜๏ธ Free Cloud | ๐Ÿค Up for Grabs | ๐ŸŽ Dev Perks | ๐Ÿš€ 1-Click Deploys | +| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | +| `111` | `105` | `128` | `67` | `72` | `21` | `30` | `42` | --- diff --git a/assets/demo.tape b/assets/demo.tape new file mode 100644 index 00000000..0a7715be --- /dev/null +++ b/assets/demo.tape @@ -0,0 +1,34 @@ +# Charm VHS script โ€” generates a crisp 15-second terminal GIF for DevShelf +# Install VHS: https://github.com/charmbracelet/vhs +# Run: vhs assets/demo.tape + +Output assets/demo.gif + +Set Shell "bash" +Set FontSize 16 +Set Width 1100 +Set Height 620 +Set Padding 20 +Set Theme "TokyoNight" +Set TypingSpeed 40ms + +Type "# 1. Search 576 CI-audited zero-paywall tools & free APIs" +Enter +Sleep 600ms +Type `npx @ritualdev-lab/devshelf search "postgres"` +Enter +Sleep 3s + +Type "# 2. Search open-source AI & MCP developer tools" +Enter +Sleep 600ms +Type `npx @ritualdev-lab/devshelf search "mcp"` +Enter +Sleep 3s + +Type "# 3. Connect DevShelf to Claude Desktop / Cursor via MCP" +Enter +Sleep 600ms +Type "npx @ritualdev-lab/devshelf --help" +Enter +Sleep 2s