Readme-runner : lancer n'importe quel projet en une commande, propulsé par GitHub Copilot CLI

Soumission au GitHub Copilot CLI Challenge organisé par 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

Construisez une application avec GitHub Copilot CLI et gagnez des places pour GitHub Universe 2026, un an de Copilot Pro+ et 1 000 USD.

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

Ce que j’ai construit

readme-runner (rdr) est un outil en ligne de commande écrit en Go qui permet de cloner, installer et lancer n’importe quel projet logiciel avec une seule commande — en lisant son README.md.

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

Pas de npm install à deviner. Pas de virtualenv à activer. Pas de “ça marche chez moi”. rdr lit le README comme un développeur humain le ferait, génère un plan d’exécution structuré grâce à un LLM, puis exécute — ou affiche — chaque étape.

Le projet est disponible ici : sony-level/readme-runner

La démonstration

# Analyser un projet GitHub (dry-run par défaut, rien n'est exécuté)
rdr https://github.com/expressjs/express

# Exécuter réellement
rdr . --dry-run=false --yes

Exemple de sortie :

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)

L’idée derrière le projet

Combien de fois avez-vous cloné un projet pour le tester, seulement pour passer 20 minutes à déchiffrer le README, trouver la bonne version de Node, installer les bonnes dépendances, et découvrir que npm start ne fonctionnait pas comme prévu ?

readme-runner part d’une idée simple : le README est la documentation principale d’un projet. Si un humain peut le lire et comprendre comment lancer l’application, un LLM peut en faire autant — et générer un plan d’exécution fiable en quelques secondes.

Comment GitHub Copilot CLI a accéléré le développement

J’ai utilisé GitHub Copilot CLI tout au long du développement de readme-runner, et son apport a été réel et concret.

Scaffolding rapide de la structure Go

Au démarrage, j’avais une vision claire de l’architecture en pipeline mais beaucoup de code répétitif à écrire pour chaque module (fetcher, scanner, llm, exec…). Copilot CLI m’a permis de décrire en langage naturel ce que je voulais :

“Génère une interface Go Provider avec une méthode GeneratePlan(ctx, readme, files) (RunPlan, error) et implémente-la pour Anthropic avec le SDK officiel”

En quelques échanges, j’avais une implémentation fonctionnelle que j’ai ensuite adaptée et testée.

Débogage du pipeline de sécurité

Le module de sécurité — qui bloque les commandes dangereuses et gère les confirmations sudo — était délicat à tester. Copilot CLI m’a aidé à générer des cas de test couvrant les edge cases (fork bomb, rm -rf /, scripts distants), que je n’aurais pas tous pensé à écrire manuellement.

Génération du schéma JSON du plan

Le format RunPlan (le JSON que le LLM doit produire) a évolué plusieurs fois. À chaque itération, j’ai demandé à Copilot CLI de mettre à jour la struct Go, le validateur, et les mocks correspondants en cohérence — ce qui aurait été fastidieux manuellement.

Architecture du pipeline

Score de clarté du README

Avant d’appeler le LLM, rdr calcule un score de clarté (0.0–1.0) pour le README :

• Score ≥ 0.6 → README comme source principale
• Score < 0.6 → fichiers projet comme source principale (Dockerfile, package.json, go.mod…)

Sécurité d’abord

rdr a été conçu avec une philosophie secure by default :

• Dry-run par défaut : aucune commande n’est exécutée sans --dry-run=false explicite
• sudo toujours demandé : même avec --yes, les commandes sudo requièrent une confirmation
• Blocklist : les commandes destructives sont bloquées avant même d’être envoyées au LLM
• Isolation workspace : toutes les opérations se font dans .rr-temp/<run-id>/

Commandes toujours bloquées :

rm -rf /       # Suppression racine
rm -rf ~       # Suppression home
mkfs           # Formatage disque
dd if=/dev/zero
chmod -R 777 /
:(){:|:&};:    # Fork bomb

Providers LLM supportés

Le provider est sélectionné automatiquement selon les variables d’environnement disponibles.

Stacks supportées

Ce que j’ai appris

Construire readme-runner m’a appris plusieurs choses :

1. Les LLMs sont bons pour lire de la documentation — mieux que je ne le pensais. Avec un bon prompt et un format JSON strict, la qualité des plans générés est remarquable.

2. La sécurité d’un outil CLI doit être pensée dès le début — ajouter une blocklist ou un système de confirmation sudo après coup est beaucoup plus complexe qu’en posant les bases dès la conception.

3. GitHub Copilot CLI réduit vraiment le coût de la boilerplate — tout le scaffolding des interfaces Go, des structs, des tests unitaires : des tâches qui auraient pris des heures ont pris des minutes.

État du projet — en cours de développement

Soyons honnêtes : la première version de readme-runner n’est pas encore finalisée. Je travaille toujours activement dessus, et la deadline du challenge est passée avant que j’aie pu soumettre une version complète.

Mais le projet avance, et j’ai préféré partager une version transparente plutôt qu’une démo trop polie qui cacherait l’état réel du travail. C’est l’une des valeurs que j’apprécie dans la communauté open source : montrer le chemin, pas seulement la destination.

Les prochaines fonctionnalités planifiées :

• Support macOS (Homebrew) et Windows
• Mode interactif pour confirmer chaque étape
• Cache des plans pour les projets déjà analysés
• Plugin system pour les stacks custom

Soutenir le projet

Si readme-runner vous intéresse ou vous inspire, la meilleure façon de le soutenir est de laisser une étoile sur GitHub — ça aide vraiment et ça me motive à continuer.

Le code source est ouvert : github.com/sony-level/readme-runner

Bon déploiement ! 🚀