Readme-runner: Launch Any Project in One Command, Powered by GitHub Copilot CLI

Submission for the GitHub Copilot CLI Challenge hosted by DEV Community × GitHub.

DEV Community · Jess Lee

Join the GitHub Copilot CLI Challenge! Win GitHub Universe Tickets, Copilot Pro+ Subscriptions and 1,000 USD in Cash

Build an application using GitHub Copilot CLI and win tickets to GitHub Universe 2026, a year of Copilot Pro+, and 1,000 USD in cash.

https://dev.to/devteam/join-the-github-copilot-cli-challenge-win-github-universe-tickets-copilot-pro-subscriptions-and-50af

What I Built

readme-runner (rdr) is a command-line tool written in Go that clones, installs, and launches any software project with a single command — by reading its README.md.

rdr https://github.com/user/awesome-project

No guessing which npm install to run. No virtualenv to activate. No “works on my machine” mysteries. rdr reads the README the way a developer would, generates a structured execution plan via an LLM, then runs — or previews — every step.

The project is open source: sony-level/readme-runner

Demo

# Analyze a GitHub project (dry-run by default — nothing executes)
rdr https://github.com/expressjs/express

# Actually run it
rdr . --dry-run=false --yes

Sample output:

Run ID: rr-20260203-1542-abc
Input: https://github.com/user/project
Source type: github

[1/7] Fetch / Workspace
  → Workspace ready at .rr-temp/rr-20260203-1542-abc
  → Fetched 142 files (1.2 MB)

[2/7] Scan
  → README found: README.md (4.2 KB)
  → Primary stack: node
  → Stack Detection: node (confidence: 0.85)

[3/7] Plan (AI)
  → README clarity score: 0.80
  → Using README as primary source
  → Using LLM provider: anthropic
  → Plan generated: node project with 2 steps

[4/7] Validate / Normalize
  → Plan is valid
  → Risk summary: Low=1, Medium=1, High=0, Critical=0

[5/7] Prerequisites
  → All 2 prerequisites available
  → node: v20.10.0
  → npm: 10.2.3

[6/7] Execute
  [1] npm ci     (medium risk)
  [2] npm start  (low risk)

The Problem It Solves

How many times have you cloned a project to test it, only to spend 20 minutes deciphering the README, tracking down the right Node version, installing dependencies, and discovering that npm start doesn’t quite work as expected?

readme-runner is built on a simple insight: the README is the primary documentation of a project. If a human can read it and understand how to run the application, an LLM can too — and generate a reliable execution plan in seconds.

How GitHub Copilot CLI Accelerated Development

I used GitHub Copilot CLI throughout the entire development of readme-runner. Its contribution was real and concrete.

Fast scaffolding of the Go architecture

At the start, I had a clear vision of the pipeline architecture but a lot of repetitive boilerplate to write for each module (fetcher, scanner, llm, exec…). Copilot CLI let me describe what I wanted in plain language:

“Generate a Go Provider interface with a GeneratePlan(ctx, readme, files) (RunPlan, error) method and implement it for Anthropic using the official SDK”

Within a few exchanges, I had a working implementation that I then adapted and tested.

Debugging the security pipeline

The security module — which blocks dangerous commands and handles sudo confirmations — was tricky to test thoroughly. Copilot CLI helped me generate test cases covering edge cases (fork bombs, rm -rf /, remote scripts) that I wouldn’t have thought to write manually.

Evolving the RunPlan JSON schema

The RunPlan format (the JSON the LLM must produce) changed several times during development. At each iteration, I asked Copilot CLI to update the Go struct, the validator, and the corresponding mocks in sync — something that would have been tedious to do by hand.

Pipeline Architecture

README Clarity Score

Before calling the LLM, rdr computes a clarity score (0.0–1.0) for the README:

• Score ≥ 0.6 → README is the primary source
• Score < 0.6 → project files take precedence (Dockerfile, package.json, go.mod…)

Security First

rdr was designed with a secure by default philosophy:

• Dry-run by default — nothing executes without an explicit --dry-run=false
• sudo always prompted — even with --yes, sudo commands require confirmation
• Command blocklist — destructive commands are rejected before ever reaching the LLM
• Workspace isolation — all operations happen inside .rr-temp/<run-id>/

Always-blocked patterns:

rm -rf /       # Root deletion
rm -rf ~       # Home deletion
mkfs           # Filesystem creation
dd if=/dev/zero
chmod -R 777 /
:(){:|:&};:    # Fork bomb

Supported LLM Providers

The provider is auto-selected based on which environment variables are available.

Supported Stacks

What I Learned

Building readme-runner taught me several things:

1. LLMs are surprisingly good at reading documentation — with a well-crafted prompt and a strict JSON schema, the quality of generated plans is remarkable.

2. CLI tool security must be designed from day one — retrofitting a blocklist or sudo confirmation system is far more complex than baking it into the foundation.

3. GitHub Copilot CLI genuinely reduces the cost of boilerplate — scaffolding Go interfaces, structs, unit tests: tasks that would have taken hours took minutes.

Project Status — Still in Progress

Let me be upfront: the first version of readme-runner is not yet finalized. I’m still actively working on it, and the challenge deadline passed before I could submit a complete version.

Other commitments got in the way, but the project keeps moving forward. I’d rather share an honest, transparent write-up than a polished demo that hides where the work actually stands. That’s one of the things I value most about open source: showing the journey, not just the destination.

Planned next steps:

• macOS (Homebrew) and Windows support
• Interactive mode to confirm each step individually
• Plan caching for previously analyzed projects
• Plugin system for custom stacks

Support the Project

If readme-runner interests you or sparks any ideas, the best way to support it is to leave a star on GitHub — it really helps and keeps me motivated to push it forward.

The source code is fully open: github.com/sony-level/readme-runner

Happy running! 🚀