RuneCLI

A terminal-first developer tool that turns real GitHub issues into grounded, timed coding quests with RuneScape-inspired progression.

Installation

RuneCLI requires Python 3.11 or newer.

pip install runecli

Or install in an isolated environment using pipx:

pipx install runecli

3-Step Quickstart

1. Login & Configure:

   rune
   

   On your first launch, Rune prompts for your GitHub token and Gemini API key, storing them in your local configuration.

2. Pick a Quest: Filter open issues on the Quest Board by keywords, Sage (repo owner), and difficulty. Review Gemma-formulated acceptance criteria and accept a quest.

3. Finish a PR & Claim XP: Follow guided Git commands in your IDE terminal, open a GitHub pull request, and run:

   rune refresh
   

   When your PR is merged before the timer expires, the quest completes and Rune awards RuneScape XP!

How It Works

• Deterministic Code Evidence: When you select an issue, Rune clones a shallow, read-only analysis cache and extracts bounded code evidence (E1–E8) matching the issue discussion.
• Grounded Quest Framing: Rune passes evidence to Google's open-weights Gemma 4 model (gemma-4-31b-it) via the Gemini API to formulate grounded quest specifications with concrete acceptance criteria.
• Guided Git Flow: Rune creates an isolated workspace directory at ~/.rune/workspaces/<quest-id>/, opens your editor (VS Code or Cursor), and prints exact setup commands. Rune only reads Git status to verify setup—you retain full control over branching, commits, and pushes.
• XP & Level Progression: Rune tracks PR status matching your quest branch. Merging before the quest timer expires earns RuneScape XP based on quest difficulty.

Contributing

We welcome contributions! Please see our Contributing Guide for local development setup, testing instructions, and pull request guidelines.

Commands

Rune provides three focused commands:

rune

Starts the interactive quest cycle:

1. Loads or prompts for credentials (GitHub token and Gemini API key).
2. Signs in to GitHub and validates authentication.
3. Checks for an installed IDE (VS Code code or Cursor cursor).
4. Checks for any active quest; if none, opens the Quest Board to search open issues.
5. Clones a bounded, read-only analysis cache and extracts evidence.
6. Generates grounded quest framings with Gemma 4 (gemma-4-31b-it).
7. Creates an isolated workspace and launches your IDE.
8. Prints guided Git setup commands and verifies your branch before starting the timer.

rune status

Displays the active quest's status, remaining time, acceptance criteria, matched pull request status, and finish instructions.

rune refresh

Checks GitHub for pull request activity matching your quest branch. When your PR is merged, transitions the quest to COMPLETED and awards RuneScape XP.

rune --version (or rune -V)

Displays the installed version of RuneCLI and exits.

Quest Board Filters

• Keywords: 3 to 8 search terms matching issue titles and bodies.
• Sage: The GitHub username or organization whose repositories to search (e.g. pallets, fastapi). Leave blank to search across public repositories.
• Unassigned: Choose Yes to find unclaimed issues (is:unassigned) or No to include assigned issues.
• Difficulty:
  • Novice: 60 min / 100 XP
  • Intermediate: 180 min / 150 XP
  • Experienced: 360 min / 250 XP
  • Master: 540 min / 400 XP

Environment Variables

Development

To work on RuneCLI from source:

git clone https://github.com/khanirfan18/runeCLI.git
cd runeCLI
python -m pip install -e ".[dev]"
python -m pytest -q

Reporting Issues

Report bugs and feature ideas on GitHub at https://github.com/khanirfan18/runeCLI/issues.

License

MIT License. See LICENSE for details.