Ralph Vercel Agent

"Me fail coding? That's unpossible!"

A looping AI coding agent with Ralph Wiggum's personality. Give it a task, and it will keep working on it until the job is done.

The Ralph Wiggum Pattern

This implements the "Ralph Wiggum" looping agent pattern:

• Don't trust "I'm done" - Just because the agent says it's finished doesn't mean it is
• Verify with backpressure - Run typecheck, lint, and tests after each completion claim
• Loop on failure - Feed errors back to the agent and let it try again
• Clear success criteria - Only stop when verification actually passes

Works best for tasks with clear completion criteria: refactors, adding functions, fixing bugs, etc.

How It Works

1. Submit a task - Provide a GitHub repo and describe what you want done
2. Ralph clones the repo - Creates a Vercel Sandbox with your code
3. The loop begins - Ralph works on the task, guided by Claude
4. Verification - After Ralph says "TASK_COMPLETE", it runs typecheck/lint/tests
5. Loop if needed - If verification fails, Ralph gets the errors and tries again
6. PR creation - Once verification passes, a pull request is automatically created

Deploy to Vercel

Environment Variables

Variable	Description
GITHUB_TOKEN	GitHub personal access token with repo access
ANTHROPIC_API_KEY	Anthropic API key for Claude
KV_REST_API_URL	Vercel KV URL (auto-set when you add KV storage)
KV_REST_API_TOKEN	Vercel KV token (auto-set when you add KV storage)

Setup Steps

1. Deploy to Vercel
2. Add a KV Database from the Storage tab
3. Set GITHUB_TOKEN and ANTHROPIC_API_KEY in environment variables
4. Redeploy

Local Development

bun install

echo "GITHUB_TOKEN=ghp_..." >> .env.local
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env.local

bun run dev

License

MIT