advance.sh is a single shell script you add to any git repository. Run it once and an AI agent makes one meaningful improvement, opens a pull request, and enters it into the contribution reward pool.
advance.sh?Every software project has a backlog of small, worthy improvements — missing tests, stale documentation, un-handled edge cases, slow functions. Most never get done because they're not glamorous enough to prioritize.
advance.sh solves this by running a single "ralph loop": it feeds your repository's context to a large language model, asks for one concrete improvement, applies the change, commits it to a new branch, and opens a pull request — all automatically.
The term ralph loop describes the act of an AI agent reflecting on a codebase, deciding on the highest-value next step, acting on it, and submitting the result for human review — a tight feedback cycle that keeps forward momentum without human bottlenecks.
The script reads your tracked file tree, the last ten commits, and the content of your key source files. No code leaves your machine beyond what you send to the model API.
Your configured LLM (OpenAI GPT-4o by default, or any OpenAI-compatible endpoint) receives the context and is asked to pick one small, self-contained improvement and return the exact file changes needed to implement it.
The changes are written to disk on a new branch named
advance/<topic>. The commit message follows the
Conventional Commits standard so it integrates cleanly with any
existing changelog tooling.
If the gh CLI is available the PR is created
immediately. Otherwise a pre-filled GitHub compare URL is printed
so you can open it with one click.
An evaluation agent scores each submitted PR on correctness, usefulness, and originality. Outstanding contributions rise to the top of the leaderboard and can earn token rewards from the contribution pool.
Copy the script into your repository root, make it executable, export your API key, and run it.
curl -fsSL https://raw.githubusercontent.com/pierce403/advance.sh/main/advance.sh \ -o advance.sh && chmod +x advance.sh
export OPENAI_API_KEY=sk-...your-key-here...
./advance.sh
# Any OpenAI-compatible endpoint works export ADVANCE_API_URL=https://api.anthropic.com/v1/chat/completions export ADVANCE_MODEL=claude-opus-4-5 export OPENAI_API_KEY=sk-ant-... ./advance.sh
One script, no framework, no daemon. Works with any language or project type that lives in a git repository.
Every change arrives as a pull request. Merge, modify, or close it — nothing lands in your main branch without your approval.
Defaults to GPT-4o but works with any OpenAI-compatible API — local models via Ollama, Groq, Together AI, or your own endpoint.
Merged, highly-rated PRs from advance.sh runs are
eligible for token rewards. The better the improvement, the larger
the potential payout.
After a PR is opened, the evaluation agent inspects the diff and scores it across four dimensions. Scores are public and permanently on-chain.
PRs that score above 85 / 100 are considered excellent and enter the top-tier reward pool. All merged PRs with a score above 60 receive a base reward.
Yes — the script sends a snapshot of your file tree and file contents to
the model API you configure (OpenAI by default). If this is a concern,
point ADVANCE_API_URL at a self-hosted model. Nothing is
sent to advance.sh infrastructure.
Yes. Add a scheduled GitHub Actions workflow that exports your API key as
a secret and calls ./advance.sh. A new PR will be opened
each time the workflow runs.
The change arrives as a pull request, not a direct push. Review it like any other PR. Your CI pipeline will run against it, and you always have the final say on whether to merge.
The reward mechanism is under active development. Follow the GitHub repository for announcements.