loop-cursor — Goal-Driven Autonomous Dev Loop for Cursor IDE / Cursor IDE 全自主开发循环引擎

English

Features

Quick Start

# Prerequisites: Node.js >= 22, Cursor IDE installed
git clone https://github.com/PerryLink/loop-cursor.git
cd loop-cursor
npm install
# Run the CLI
cd packages/cli
npx tsx src/index.ts --goal "Build a REST API for a todo app"
# Or via Bun CLI wrapper (spawns Node.js child process)
bun run --bun packages/cli/src/index.ts --goal "Add dark mode support"

Prerequisites

Installation

1. Clone the repository

git clone https://github.com/PerryLink/loop-cursor.git
cd loop-cursor

2. Install dependencies

# Install core engine dependencies
cd packages/loop-core
npm install
# Install Cursor SDK adapter dependencies
cd ../adapter-cursor-sdk
npm install
# Install CLI dependencies
cd ../cli
npm install
# Return to project root
cd ../..

3. Build (type-check only -- no compilation required)

# From the project root
npx tsc -b packages/loop-core packages/adapter-cursor-sdk packages/cli

4. Verify the installation

# Check SDK compatibility (5 checks: Node version, SDK load, version match, API key, response format)
cd packages/adapter-cursor-sdk
npx tsx src/sdk-check.ts
# Run a minimal probe to verify the engine works
npx tsx src/probe.ts

Configuration

Project configuration file

{
 "mode": "auto",
 "max_cycles": 5,
 "max_part1_rounds": 5,
 "convergence_rounds": 2,
 "route_repeat_max": 3,
 "user_request": "Build a REST API for a todo app",
 "model": "claude-sonnet-4-20250514",
 "sdk_version": "1.0.12"
}

Configuration options

Environment variables

Runtime artifacts

Usage

CLI commands

# Start a new loop with a goal
cd packages/cli
npx tsx src/index.ts --goal "Build a REST API for a todo app"
# Start with a specific run mode
npx tsx src/index.ts --goal "Add dark mode support" --mode safe
# Start with a specific model
npx tsx src/index.ts --goal "Refactor the auth module" --model claude-opus-4-20250514
# Resume from an existing state file
npx tsx src/index.ts --state-file .cursor/loop-cursor/state.json
# Set max cycles
npx tsx src/index.ts --goal "Implement user registration" --max-cycles 10

CLI flags

Via Bun CLI wrapper

# The Bun wrapper spawns a Node.js child process internally
bun run --bun packages/cli/src/index.ts --goal "Add dark mode support"

Project Structure

loop-cursor/
├── .github/
│ └── workflows/
│ └── ci.yml # CI pipeline (lint, test, build, audit)
├── packages/
│ ├── loop-core/ # Core engine (shared types, config, convergence, router, state machine)
│ │ └── src/
│ │ ├── types.ts # Shared type system (LoopState, PlatformAdapter, enums, etc.)
│ │ ├── config.ts # Configuration management (defaults, merging, validation)
│ │ ├── engine-loop.ts # 22-step orchestration engine (main loop)
│ │ ├── router.ts # Routing engine (P0/P1/P2 routing decisions)
│ │ ├── convergence.ts # Convergence engine (convergence detection, counter updates)
│ │ ├── issue-classifier.ts # Issue classifier (P0/P1/P2 severity determination)
│ │ ├── state-machine.ts # File-based state machine (state.json read/write/atomic)
│ │ ├── schema.ts # JSON Schema validation for state files
│ │ ├── sap-parser.ts # SAP block parser (<<<LOOP_STATE>>> extraction)
│ │ ├── gate-content-safety.ts # Content safety gate (G1)
│ │ ├── worktree.ts # Git worktree management
│ │ ├── platform-adapter.ts # PlatformAdapter interface definition
│ │ └── index.ts # Core package entry point
│ ├── adapter-cursor-sdk/ # Cursor SDK platform adapter
│ │ └── src/
│ │ ├── adapter.ts # CursorPlatformAdapter (7-method implementation)
│ │ ├── rules-generator.ts # Dynamic .cursor/rules/*.mdc generator
│ │ ├── hooks-generator.ts # Dynamic hooks.json generator
│ │ ├── context-injector.ts # Cross-turn context bridge (P0-2 workaround)
│ │ ├── sdk-check.ts # SDK compatibility check (5 checks)
│ │ ├── probe.ts # Feasibility probes (3 probes + verdict matrix)
│ │ ├── rule-generator.ts # Individual rule file generator
│ │ └── index.ts # Adapter package entry point
│ └── cli/ # CLI entry point (argument parsing, child process spawning)
│ └── src/
│ └── index.ts # CLI main entry
├── tests/ # Test suite
│ ├── test-engine-loop.test.ts # Engine loop integration tests
│ ├── test-issue-classifier.test.ts # Issue classifier unit tests
│ ├── test-state-machine.test.ts # State machine unit tests
│ ├── test-router.test.ts # Router unit tests
│ ├── test-convergence.test.ts # Convergence engine unit tests
│ └── test-adapter.test.ts # Adapter unit tests
├── examples/ # Example projects
│ ├── example-1-basic/
│ ├── example-2-multi-phase/
│ └── example-3-worktree/
├── tsconfig.json # Root TypeScript configuration
├── package.json # Monorepo root package
├── README.md # This file
└── LICENSE # Apache License 2.0

Troubleshooting

"Engine is locked" error

rm .cursor/loop-cursor/.lock

"NGHTTP2_FRAME_SIZE_ERROR" with Bun

npx tsx packages/cli/src/index.ts --goal "your goal"

"Cannot find module @cursor/sdk"

cd packages/adapter-cursor-sdk
npm install

node -e "const pkg = require('@cursor/sdk/package.json'); console.log(pkg.version)"

"CURSOR_API_KEY not set"

export CURSOR_API_KEY="your-api-key-here"

$env:CURSOR_API_KEY = "your-api-key-here"

Agent calls failing repeatedly

State file corruption

cp .cursor/loop-cursor/state.json.bak .cursor/loop-cursor/state.json

Tests fail with module resolution errors

# From project root
cd packages/loop-core && npm install && cd ../..
cd packages/adapter-cursor-sdk && npm install && cd ../..
cd packages/cli && npm install && cd ../..

Node.js version too old

node --version # Should be v22.x.x or later

FAQ

Q: Why does this require Node.js >= 22 instead of Bun?

Q: What are the .cursor/rules/*.mdc files generated at runtime?

Q: How does loop-cursor handle session disconnects or IDE restarts?

Related Projects

License

中文

功能特性

快速开始

# 前置条件:Node.js >= 22,已安装 Cursor IDE
git clone https://github.com/PerryLink/loop-cursor.git
cd loop-cursor
npm install
# 运行 CLI
cd packages/cli
npx tsx src/index.ts --goal "为 todo 应用构建 REST API"
# 或通过 Bun CLI 包装器(内部启动 Node.js 子进程)
bun run --bun packages/cli/src/index.ts --goal "添加深色模式支持"

前置条件

安装

1. 克隆仓库

git clone https://github.com/PerryLink/loop-cursor.git
cd loop-cursor

2. 安装依赖

# 安装核心引擎依赖
cd packages/loop-core
npm install
# 安装 Cursor SDK 适配器依赖
cd ../adapter-cursor-sdk
npm install
# 安装 CLI 依赖
cd ../cli
npm install
# 返回项目根目录
cd ../..

3. 构建(仅类型检查 -- 无需编译)

# 从项目根目录执行
npx tsc -b packages/loop-core packages/adapter-cursor-sdk packages/cli

4. 验证安装

# 检查 SDK 兼容性(5 项检查:Node 版本、SDK 加载、版本匹配、API 密钥、响应格式)
cd packages/adapter-cursor-sdk
npx tsx src/sdk-check.ts
# 运行最小探测以验证引擎工作正常
npx tsx src/probe.ts

配置

项目配置文件

{
 "mode": "auto",
 "max_cycles": 5,
 "max_part1_rounds": 5,
 "convergence_rounds": 2,
 "route_repeat_max": 3,
 "user_request": "为 todo 应用构建 REST API",
 "model": "claude-sonnet-4-20250514",
 "sdk_version": "1.0.12"
}

配置选项

环境变量

运行时生成文件

使用方法

CLI 命令

# 使用目标启动新循环
cd packages/cli
npx tsx src/index.ts --goal "为 todo 应用构建 REST API"
# 使用指定运行模式启动
npx tsx src/index.ts --goal "添加深色模式支持" --mode safe
# 使用指定模型启动
npx tsx src/index.ts --goal "重构认证模块" --model claude-opus-4-20250514
# 从现有状态文件恢复
npx tsx src/index.ts --state-file .cursor/loop-cursor/state.json
# 设置最大循环次数
npx tsx src/index.ts --goal "实现用户注册" --max-cycles 10

CLI 参数

通过 Bun CLI 包装器

# Bun 包装器内部启动 Node.js 子进程
bun run --bun packages/cli/src/index.ts --goal "添加深色模式支持"

项目结构

loop-cursor/
├── .github/
│ └── workflows/
│ └── ci.yml # CI 流水线(lint、test、build、audit)
├── packages/
│ ├── loop-core/ # 核心引擎(共享类型、配置、收敛、路由、状态机)
│ │ └── src/
│ │ ├── types.ts # 共享类型系统(LoopState、PlatformAdapter、枚举等)
│ │ ├── config.ts # 配置管理(默认值、合并、验证)
│ │ ├── engine-loop.ts # 22 步编排引擎(主循环)
│ │ ├── router.ts # 路由引擎(P0/P1/P2 路由决策)
│ │ ├── convergence.ts # 收敛引擎(收敛检测、计数器更新)
│ │ ├── issue-classifier.ts # 问题分类器(P0/P1/P2 严重级别判定)
│ │ ├── state-machine.ts # 基于文件的状态机(state.json 读写/原子操作)
│ │ ├── schema.ts # 状态文件 JSON Schema 验证
│ │ ├── sap-parser.ts # SAP 块解析器(<<<LOOP_STATE>>> 提取)
│ │ ├── gate-content-safety.ts # 内容安全门禁(G1)
│ │ ├── worktree.ts # Git worktree 管理
│ │ ├── platform-adapter.ts # PlatformAdapter 接口定义
│ │ └── index.ts # 核心包入口
│ ├── adapter-cursor-sdk/ # Cursor SDK 平台适配器
│ │ └── src/
│ │ ├── adapter.ts # CursorPlatformAdapter(7 方法实现)
│ │ ├── rules-generator.ts # 动态 .cursor/rules/*.mdc 生成器
│ │ ├── hooks-generator.ts # 动态 hooks.json 生成器
│ │ ├── context-injector.ts # 跨轮次上下文桥接(P0-2 变通方案)
│ │ ├── sdk-check.ts # SDK 兼容性检查(5 项检查)
│ │ ├── probe.ts # 可行性探测(3 项探测 + 判定矩阵)
│ │ ├── rule-generator.ts # 单个规则文件生成器
│ │ └── index.ts # 适配器包入口
│ └── cli/ # CLI 入口(参数解析、子进程启动)
│ └── src/
│ └── index.ts # CLI 主入口
├── tests/ # 测试套件
│ ├── test-engine-loop.test.ts # 引擎循环集成测试
│ ├── test-issue-classifier.test.ts # 问题分类器单元测试
│ ├── test-state-machine.test.ts # 状态机单元测试
│ ├── test-router.test.ts # 路由单元测试
│ ├── test-convergence.test.ts # 收敛引擎单元测试
│ └── test-adapter.test.ts # 适配器单元测试
├── examples/ # 示例项目
│ ├── example-1-basic/
│ ├── example-2-multi-phase/
│ └── example-3-worktree/
├── tsconfig.json # 根 TypeScript 配置
├── package.json # Monorepo 根包配置
├── README.md # 本文件
└── LICENSE # Apache License 2.0

故障排除

"Engine is locked" 错误

rm .cursor/loop-cursor/.lock

使用 Bun 时出现 "NGHTTP2_FRAME_SIZE_ERROR"

npx tsx packages/cli/src/index.ts --goal "你的目标"

"Cannot find module @cursor/sdk"

cd packages/adapter-cursor-sdk
npm install

node -e "const pkg = require('@cursor/sdk/package.json'); console.log(pkg.version)"

"CURSOR_API_KEY not set"

export CURSOR_API_KEY="your-api-key-here"

$env:CURSOR_API_KEY = "your-api-key-here"

Agent 调用反复失败

状态文件损坏

cp .cursor/loop-cursor/state.json.bak .cursor/loop-cursor/state.json

测试因模块解析错误失败

# 从项目根目录执行
cd packages/loop-core && npm install && cd ../..
cd packages/adapter-cursor-sdk && npm install && cd ../..
cd packages/cli && npm install && cd ../..

Node.js 版本过旧

node --version # 应为 v22.x.x 或更高

常见问题

Q: 为什么需要 Node.js >= 22 而不是 Bun?

Q: 运行时生成的 .cursor/rules/*.mdc 文件是什么?

Q: loop-cursor 如何处理会话断开或 IDE 重启?

相关项目

许可证