10x-Agent-Loop

# 🚀 10x-Agent-Loop

**Break through Cursor / Windsurf quota limits and achieve true autonomous programming loops.**

[中文](readme-zh.md) | [English](readme.md)

---

Often, your Agent is forced to stop due to exhausted Fast Request quota, or gets stuck in loops due to context pollution.

**10x-Agent-Loop** brings you through file watching technology and multi-runtime support:

*   💰 **Infinite Refills**: One Fast Request, unlimited interactions—make your 500 quota feel like 5000.
*   🧠 **Consultant Mode**: When AI gets stuck, automatically generate structured consultation emails and leverage external clean environments (Gemini/Claude) to break through.
*   🛡️ **Context Cleaning**: Force structured thinking to prevent Agents from falling into local optima.

> **⚠️ Prerequisites**:
> 1. One of the following runtimes (prefer system-built-in versions, no installation required):
>    *   PowerShell (Built-in on Windows)
>    *   CMD (Built-in on Windows)
>    *   Bash (Built-in on Linux/macOS)
>    *   [Bun](https://bun.sh/) (Requires installation)
>    *   [Node.js](https://nodejs.org/) (v16+, requires installation)
>    *   [Python](https://www.python.org/) (v3.6+, requires installation)
> 2. **⚠️ Important**: Using **Composer Agent Mode** in Cursor or Windsurf (not normal chat mode). This solution only works in Agent mode because it requires AI to execute terminal commands.

---

## ⚡️ Quick Start

**Core Principle**: 1. **Script** suspends the process; 2. **Rules** tell AI to run the script.

```
┌──────┐    ┌──────────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ User │───>│Cursor Composer│───>│Rules File│───>│AI Executes│───>│Run Script│
└──────┘    │ (Agent Mode) │    │cursor-rules│    └────┬───┘    │ask-followup│
            └──────────────┘    └──────────┘           │         └─────┬────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │ File Watch   │
                                                       │         │NEXT_STEP.md  │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │User Input    │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       └────────────────┘
                                                                  │
                                                                  ▼
                                                           ┌──────────────┐
                                                           │AI Continues  │
                                                           └──────┬───────┘
                                                                  │
                                                                  └──> (Loop continues...)
```

### 1. Deploy Files

Copy the corresponding files directly to your project. **All versions have the same functionality, choose one that fits your environment**.

| Your Environment | Copy Script (to project root) | Copy Rules (to `.cursor/rules/` or root) |
| :--- | :--- | :--- |
| **Windows** (Recommended, built-in) | `files/pwsh/ask-followup.ps1` | `files/pwsh/cursor-rules.mdc` |
| **Mac / Linux** (Built-in) | `files/shell/ask-followup.sh` | `files/shell/cursor-rules.mdc` |
| **Node.js** | `files/node/ask-followup.js` | `files/node/cursor-rules.mdc` |
| **Python** | `files/python/ask-followup.py` | `files/python/cursor-rules.mdc` |
| **Bun** | `files/bun/ask-followup.ts` | `files/bun/cursor-rules.mdc` |

> ⚠️ **Important**: **Copy the file itself directly**. Manually creating and pasting may cause **encoding format (UTF-8/BOM) or line ending (CRLF/LF)** issues, preventing script execution.
>
> **Rules File Location**:
> - Recommended for newer Cursor: Copy to `.cursor/rules/` directory (ensure "Rules for AI" is enabled in Cursor settings)
> - Or root directory: Copy to project root and name it `.cursorrules`
>
> **Linux/Mac Users**: Remember to add execute permission: `chmod +x ask-followup.sh`

### 2. Start the Loop

```
┌──────────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│Open Composer │──>│Enter Req │──>│AI Executes│──>│Run Script│──>│Show Spinner│
│  (Ctrl+I)    │   └──────────┘   └──────────┘   │ask-followup│  │Spinning..│
└──────────────┘                                 └─────┬──────┘   └─────┬────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │Generate      │
                                                       │         │NEXT_STEP.md  │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │User Edits File│
                                                       │         │Enter Command │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │  Save File    │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │AI Detects    │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       │                ▼
                                                       │         ┌──────────────┐
                                                       │         │  Continue?    │
                                                       │         └──────┬───────┘
                                                       │                │
                                                       │        ┌──────┴──────┐
                                                       │        │              │
                                                       │        ▼              ▼
                                                       │   ┌────────┐    ┌──────────┐
                                                       │   │  Yes   │    │   No     │
                                                       │   └───┬────┘    └─────┬────┘
                                                       │       │              │
                                                       │       │              ▼
                                                       │       │         ┌──────────┐
                                                       │       │         │End Loop  │
                

[truncated…]