runr-ai 0.1.0

Automatically set up and run any GitHub repository using AI-powered dependency resolution

runr

Automatically set up and run any GitHub repository using AI-powered dependency resolution.

runr https://github.com/karpathy/nanoGPT

That's it. runr clones the repo, reads every dependency file, resolves conflicts via an LLM, creates an isolated virtual environment, installs everything, and runs the project — self-healing up to 5 times if anything goes wrong.

---

Install

pip install runr
# or, for latest:
pip install git+https://github.com/runr-cli/runr

Requires Python 3.10+. Optionally install uv for faster installs:

pip install uv

Setup

Set your Groq API key (get one free at console.groq.com):

export GROQ_API_KEY=gsk_...

Usage

# Run a GitHub repo
runr https://github.com/karpathy/nanoGPT

# Run a local repo
runr ./my_local_project

# Force Python version
runr https://github.com/user/repo --python 3.11

# CPU-only (skip CUDA deps)
runr https://github.com/user/repo --no-gpu

# Preview plan without running
runr https://github.com/user/repo --dry-run

# Override entry point
runr https://github.com/user/repo --entry src/train.py

# Verbose (shows install logs + resolved requirements)
runr https://github.com/user/repo --verbose

# Private repo
runr https://github.com/org/private-repo --token ghp_...
# or set GITHUB_TOKEN env var

What happens

◆ runr v0.1.0

● Cloning karpathy/nanoGPT...         ✓  (2.3s)
● Detecting dependencies...           ✓  14 imports detected, 2 dep files
● Environment: Python 3.11.9, Darwin arm64, CPU only
● Resolving conflicts...              ✓  12 packages resolved
● Creating environment & installing...✓  installed via uv in 18.4s
● Entry point: python train.py

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[live repo output streams here]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Successfully completed after 1 attempt(s)

If the run fails, runr self-heals:

✗ Run failed (attempt 1/5)
  Error: No module named 'flash_attn'

◆ Healing...
  → pip install flash-attn==2.3.0
  Installing flash-attn compatible with CUDA 12.1

✓ Fix applied
● Retrying... ✓ Success

How it works

Step	Module	What it does
Clone	cli.py	Clones to a temp directory; never touches your original files
Detect	detector.py	Reads requirements.txt, setup.py, pyproject.toml, environment.yml, Dockerfile, scans .py imports
Resolve	resolver.py	Sends everything to Groq llama-3.3-70b-versatile; gets back a pinned requirements.txt
Install	installer.py	Creates venv via uv venv (falls back to python -m venv), installs pinned deps
Run	runner.py	Streams live output; on failure passes error to healer
Heal	healer.py	LLM returns a structured fix: install package / modify file / set env var

Caching

Resolved requirements are cached in ~/.runr/cache/ keyed by a SHA-256 hash of all dependency files. Same repo + same deps = instant resolution skip. Use --no-cache to force a fresh resolve.

Logs

Full logs are written to ~/.runr/logs/<repo>_<timestamp>.log.

Environment detection

runr automatically detects:

• Python version and OS/arch
• CUDA version (nvcc --version, nvidia-smi)
• GPU presence
• Already-installed packages (avoids re-pinning what's there)

Supported dependency files

• requirements.txt
• requirements-dev.txt
• setup.py
• setup.cfg
• pyproject.toml
• environment.yml (conda)
• Dockerfile (extracts RUN pip install lines)
• Implicit imports scanned from all .py files

Error handling

Error	How runr handles it
torch CUDA mismatch	Detects CUDA version, installs correct +cu* build
Package not on PyPI	LLM skips or finds alternative
Python version mismatch	Reads requires-python, suggests correct version
Missing system deps	Prints human-readable install instructions
Private repo	Prompts for --token or GITHUB_TOKEN
Notebook-only repo	Launches jupyter notebook

License

MIT