Ralph Loop for Antigravity (Updated)

Fork Notice: This is a fork of Ralph Loop for Antigravity by Abhishek Bhakat, released under the MIT License.

Key improvements in this fork:

• 🌐 Chinese language support (简体中文) — UI, commands, and configuration descriptions
• 🔍 Smart file auto-detection — automatically discovers PRD, TASKS, PROMPT, SPEC, and 20+ file patterns in your workspace
• 🔄 Auto-reconnect with breakpoint resume (断点续跑) — automatically recovers from Antigravity server crashes with exponential backoff (up to 5 retries, 15s–120s delays)
• 💾 Settings persistence — remembers your last used model, mode, prompt file, and other settings across sessions
• 🤖 Latest model support: Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), Gemini 3.1 Pro (High/Low), GPT-OSS 120B
• ⚡ Updated API integration for Antigravity v1.107+ (JSON-based REST API)

A VSCode extension that brings the Ralph Loop autonomous AI agent methodology to Antigravity.

Overview

Developers using AI coding assistants face two key challenges:

1. Context window limitations - LLMs forget important context mid-task
2. Constant oversight required - AI cannot work autonomously for extended periods

The Ralph Loop methodology solves this by externalizing memory to files and running AI agents in iterative loops. This extension provides intuitive controls for managing these loops directly within VS Code.

Quick Start

1. Install the extension from the VSIX file
2. Create your PRD/spec file (see Task File Format below)
   • Use Planning mode in Antigravity to help create a proper PRD with discrete tasks
3. Open the Ralph Loop sidebar via the Activity Bar icon
4. Configure your session in the sidebar:
   • Select task file (default: docs/tasks/PRD.md)
   • Set progress file (default: docs/tasks/progress.txt)
   • Choose mode and model
   • Set max iterations
5. Start the loop using the play button in the sidebar

Recommended Workflow (Antigravity):
Use Planning mode to create your PRD/spec file with well-defined tasks.
Then switch to Fast mode to run the Ralph Loop for execution.

File Structure

The extension uses a simple file-based architecture:

File	Purpose	Description
docs/tasks/PRD.md	Task Specification	Your tasks/requirements. Read-only for agent.
docs/tasks/progress.txt	Progress Log	Agent appends progress here. Source of truth for completion.
docs/tasks/prompt.md	Instructions	Optional custom instructions for the agent.

Task File Format

The task file is read-only - the agent never modifies it. Write a proper PRD or specification document, but organize it into discrete, actionable tasks so the agent can identify what to work on next by cross-referencing progress.txt.

# PRD: User Management System

## Overview
Build a user management system with authentication, profiles, and admin controls.

## Task 1: Authentication
Implement JWT-based authentication with login/logout endpoints.
- POST /api/auth/login
- POST /api/auth/logout
- Token refresh mechanism

## Task 2: User Profiles
Create user profile CRUD operations.
- GET/PUT /api/users/:id
- Profile picture upload
- Email verification

## Task 3: Admin Dashboard
Build admin interface for user management.
- List all users with pagination
- Suspend/activate accounts
- View user activity logs

The key is clear task boundaries - each ## Task N: section should be a self-contained unit of work that the agent can complete in one iteration.

Progress File Format

The agent appends entries to track completion. This is how it knows which tasks are done:

[2026-01-21 10:30] Started: Task 1 - User Authentication
[2026-01-21 10:45] Created auth module in src/auth/
[2026-01-21 11:00] Completed: Task 1 - User Authentication
[2026-01-21 11:05] Started: Task 2 - Database Migrations

Features

🌐 Chinese Language Support (简体中文)

All UI elements, commands, and configuration descriptions are fully translated to Simplified Chinese. The extension automatically adapts when VS Code is set to Chinese locale.

🔄 Auto-Reconnect & Breakpoint Resume (断点续跑)

When the Antigravity server crashes or restarts mid-iteration:

• Automatic detection of connection errors (ECONNREFUSED, HTTP/2 session destroyed, etc.)
• Exponential backoff: waits 15s → 30s → 60s → 120s → 120s (up to 5 retries, ~6 minutes total)
• Visual progress notification with countdown timer (cancellable)
• Breakpoint resume: retries the failed iteration without losing progress
• Clear ═══ 断点续跑 ═══ markers in the output log

💾 Settings Persistence

Your session configuration (model, mode, max iterations, prompt file, etc.) is automatically saved to workspace state and restored when you reopen the project.

🔍 Smart File Auto-Detection

When selecting task or prompt files, the extension automatically scans your workspace for matching files:

• Task files: PRD.md, TASKS.md, TODO.md, SPEC.md, REQUIREMENTS.md, BACKLOG.md, ROADMAP.md, PLAN.md, ISSUES.md (+ case variants and .txt)
• Prompt files: PROMPT.md, INSTRUCTIONS.md, SYSTEM_PROMPT.md, AGENT_PROMPT.md, CONTEXT.md (+ case variants and .txt)
• Also searches subdirectories for files containing these keywords
• QuickPick shows detected files with a "custom path" fallback option

Activity Bar & Sidebar

Ralph Loop has a dedicated Activity Bar icon. The sidebar shows:

• Session: Current status, mode, model, iteration count, elapsed time
• Configuration: All configurable options (click to change)
  • Mode (Fast/Planning)
  • Model
  • Max Iterations
  • Prompt File
  • Task File
  • Progress File

Status Bar

A persistent status bar item displays:

• Loop state: Running, Paused, or Stopped
• Current iteration: 15/50
• Elapsed time: 2m 34s

Output Channel

The Ralph Loop output channel provides:

• Streaming agent responses
• Iteration markers and phase tracking
• Progress indicators
• Reconnection status and breakpoint resume logs

Commands

Command	Description
Ralph: Start Ralph Loop	Start a new loop session
Ralph: Stop Ralph Loop	Stop the loop gracefully
Ralph: Pause/Resume Ralph Loop	Toggle pause state
Ralph: Emergency Stop Ralph Loop	Immediately stop the loop

Configuration

Settings

Configure Ralph Loop via VS Code Settings (Preferences: Open Settings):

Setting	Default	Description
ralphLoop.maxIterations	200	Maximum iterations per loop
ralphLoop.defaultMode	Planning	Default mode
ralphLoop.defaultModel	Claude Opus 4.6 (Thinking)	Default AI model
ralphLoop.promptFile	None	Default prompt file
ralphLoop.taskFile	PRD.md	Default task file
ralphLoop.progressFile	progress.txt	Default progress file

How It Works

1. Fresh Context Per Iteration: Each iteration spawns a fresh cascade session, sending structured instructions that reference your task and progress files.

2. Structured Instructions: The agent receives clear instructions:

   • Read tasks from your task file
   • Check progress in your progress file
   • Complete exactly one task
   • Append progress (never delete)
   • Commit changes

3. File-Based Memory: Progress persists on disk between iterations in progress.txt, not in the agent's memory.

4. Graceful Stop: The stop command waits for the current iteration to complete.

5. Emergency Stop: Immediately terminates the loop.

Automatic Loop Completion

When you start a loop, Ralph generates a unique completion marker (e.g., ralph-done-a3x9k). The agent is instructed to append this marker to the progress file when ALL tasks are complete.

Before each iteration, Ralph checks the last few lines of your progress file for this marker. If found, the loop ends automatically - no manual stop needed.

This means:

• The loop stops on its own when work is done
• Each loop session has a unique marker (prevents false positives from old runs)
• You can still manually stop anytime if needed

Troubleshooting

"No task file selected"

Select a task file in the sidebar Configuration section.

"No workspace folder open"

Open a folder in VS Code before starting Ralph Loop.

Loop not responding

Use Ralph: Emergency Stop Ralph Loop from the Command Palette.

Wrong workspace

The extension opens your task/prompt file before starting to ensure the agent works in the correct workspace.

Links

• Open VSX Marketplace
• GitHub Repository (Fork)
• Report Issues
• Original Project by Abhishek Bhakat

Requirements

• VS Code 1.83.0 or later
• Antigravity in agent driven mode
• A workspace folder with task files

License

MIT - Original copyright © 2026 Abhishek Bhakat. Fork maintained by alexj11324.

---

Turn Antigravity into an autonomous, iterative coding agent.