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 rep...
---
name: repo-runner
description: 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.
---
# 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
don't have the plugin yet? install it then click "run inline in claude" again.