# Repo Runner

> Bootstrap and run a GitHub project by following its docs (README/docs), with safeguards for untrusted install/run steps. Use when the user gives a GitHub repo and asks to run it locally.

- Skill: `dvcrn/repo-runner` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/repo-runner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/repo-runner/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/repo-runner

---


# Repo Runner (run a GitHub project)

Goal: given a GitHub URL or a downloaded folder, get the project running **as its docs intend**, without guessing dangerously.

## Inputs to ask for

- Repo source: GitHub URL (preferred) or local path
- Target: `dev` (local dev server) / `build` / `test`
- Constraints: allow installing deps? allow running postinstall scripts? allow Docker?

## Safety rules (must follow)

- Treat repo code as untrusted.
- Before running `npm/pnpm/yarn install` (or any `curl | bash`), ask for confirmation.
- Never paste or store secrets. If `.env` is needed, ask user to provide values out-of-band.

## Workflow

1. Clone / prepare workspace
   - Clone to `<openclaw-workspace>/projects/<repo>` (create `projects/` if missing)
   - Typical workspace path is `$HOME/.openclaw/workspace`, but don’t assume.
   - If already exists, ask before `git pull` or deleting anything.

2. Find the canonical docs
   - Prefer `README.md` + `docs/` + `CONTRIBUTING.md`
   - Extract: prerequisites (Node/Python/Docker/Go/Rust), install steps, env vars, run command(s), ports.

3. Detect project type(s)
   - From the `repo-runner` skill directory (typically `<openclaw-workspace>/skills/repo-runner`), run: `bash scripts/detect_project.sh <repoDir>`
   - A repo can match multiple types (e.g. `type=node` + `type=docker`). Use docs to choose the canonical path.

4. Set up prerequisites
   - Verify required runtimes exist (Node/pnpm/yarn, Python, Docker, Go, Rust)
   - If missing, propose options (install locally, use Docker, or switch to a supported env)

5. Configure env
   - If `.env.example` exists, copy to `.env` **only after confirmation**
   - Ask user to fill required keys

6. Install dependencies (after confirmation, based on project type)

   - Node (when `package.json` exists)
     - Prefer lockfile-safe commands:
       - `pnpm install --frozen-lockfile` (if `pnpm-lock.yaml`)
       - `yarn install --frozen-lockfile` (if `yarn.lock`)
       - `npm ci` (if `package-lock.json`)
     - If unsure, run: `bash scripts/suggest_node_commands.sh <repoDir>`

   - Python (when `pyproject.toml` / `requirements.txt` exists)
     - Create and use a virtualenv (don’t install into system Python).
     - Typical patterns (follow docs first):
       - `python -m venv .venv && source .venv/bin/activate`
       - `pip install -r requirements.txt`
       - If `pyproject.toml`: use the tool specified by docs (commonly `poetry install` or `pip install -e .`).

   - Rust (when `Cargo.toml` exists)
     - `cargo build` / `cargo test` / `cargo run` (follow docs for features/flags)

   - Go (when `go.mod` exists)
     - `go test ./...`
     - `go run .` or `go build ./...` (follow docs for main package path)

   - Docker (when `docker-compose.yml` / `Dockerfile` exists)
     - Prefer the documented compose path when present:
       - `docker compose up` (or `docker-compose up` depending on docs)

7. Run
   - Use the docs’ recommended run target (dev server, CLI, compose stack, etc.)
   - Capture logs, detect common failures, iterate

## Common outputs to report back

- Exact commands run (copy/paste friendly)
- URL/port to open
- Next steps (build/test) and known caveats