AgentLoop

Product Introduction

1. Definition: AgentLoop is an open-source, local-first AI agent orchestration framework for autonomous software development. It operates as a Node.js daemon that coordinates discrete "Codex" workers and independent critics in a cyclical build-review-improve loop.
2. Core Value Proposition: It exists to eliminate the manual "babysitting" and context-relaying typically required in AI-assisted coding. By automating the handoff between planning, execution, and critique against a fixed standard, it enables developers to set a bounded goal once and let the system work autonomously until the defined quality rubric is met, significantly increasing developer productivity and code quality.

Main Features

1. Fresh Context Per Cycle: Each iteration starts a brand new, sandboxed worker process with no memory of prior cycles beyond the project files. This prevents error compounding, hallucination cascades, and context window pollution common in long-running chat-based agents. It uses a clean execution environment for every build step.
2. Independent Critic with Project Rubric: A separate, fresh critic process evaluates each cycle's output against a static GUIDELINES.md file. This critic is not forced to find failures; it performs an independent assessment, catching defects that existing test suites may miss (like the documented percent-decoding bug) and providing concrete, actionable fix notes for the next cycle.
3. Filesystem as Persistent Memory: The system's state and "memory" are carried forward exclusively through changes to the project's source code, test files, and documentation in the local repository. This provides full observability, auditability, and aligns with standard developer workflows, making the agent's work tangible and integrable.
4. Local-First & Observable Dashboard: The entire loop runs locally on the developer's machine (Node.js 18+, Git), requiring only an authenticated CLI for the AI engine. A live web dashboard (localhost:5757) provides real-time observability into cycles, verdicts, transcripts, costs, and file changes, with the ability to cancel runs at any point.
5. MCP (Model Context Protocol) Integration for ChatGPT Control: Planning and high-level control remain in the user's preferred ChatGPT interface via MCP, separating the strategic planning phase from local execution. Users can initiate goals and check status without leaving their chat environment.

Problems Solved

1. Pain Point: The inefficient relay. Developers acting as a manual middleware between an AI planner (e.g., ChatGPT) and the execution environment, constantly copying code, providing context, and managing the feedback loop.
2. Pain Point: Degrading performance of long-running AI agents. Traditional agents suffer from context window limits, increasing costs, and compounding errors as conversation history grows.
3. Target Audience: Software Engineers, Full-Stack Developers, and Tech Leads who use AI coding assistants for feature development, code migrations, test hardening, and system refactoring. It's particularly valuable for solo developers or small teams looking to automate well-scoped development tasks.
4. Use Cases:
   • Feature Implementation: "Add CSV export across the UI, API, and regression suite."
   • Code Migration: Upgrading a library or framework version across a codebase.
   • Test Hardening: Improving test coverage and robustness based on a defined rubric.
   • Polish Mode: Iterating on a already-functional feature until it meets a "SHIP"-grade quality standard beyond a simple "PASS."

Unique Advantages

1. Differentiation vs. Chat-Based Agents: Unlike ChatGPT Code Interpreter or persistent agent chats, AgentLoop's cycle-based model with fresh contexts prevents context degradation, makes each step atomic and debuggable, and uses the filesystem—not a volatile chat history—as the source of truth.
2. Differentiation vs. Traditional CI/CD: It integrates the AI critic as a first-class citizen in the development loop, performing qualitative and stylistic review that goes beyond binary test pass/fail states, catching logical and standards-based defects early.
3. Key Innovation: The decoupled "worker-critic" cycle with a persistent GUIDELINES.md rubric. This formalizes "definition of done" into a machine-executable checklist that is enforced independently of the builder, creating a self-improving system where failures generate concrete evidence for the next attempt.

Frequently Asked Questions (FAQ)

1. What is AgentLoop and how does it work? AgentLoop is an autonomous coding framework that runs a loop: a fresh AI worker builds code based on a goal, a separate AI critic reviews it against your GUIDELINES.md rubric, and the cycle repeats using the updated project files until the critic's verdict is "PASS" or "SHIP."
2. Is AgentLoop a cloud service or does it run locally? AgentLoop is a zero-dependency Node.js application that runs locally on your machine. All code execution, file editing, and AI processing (via your configured CLI) happens in your local environment, ensuring privacy, security, and full control.
3. What AI models does AgentLoop support? The initial release is built for and ships with support for Codex-compatible engines via CLI. However, its architecture is pluggable by design, with MCP for planning and an explicit engine boundary intended to support additional AI models in the future.
4. How is AgentLoop different from GitHub Copilot or Cursor? While Copilot and Cursor are primarily real-time code completion and in-editor assistance tools, AgentLoop is an orchestrator for autonomous task completion. It manages multi-step projects from a single goal, handling the entire build-critique-iterate loop outside the editor, akin to an automated junior developer working from a ticket.
5. What does "POLISH mode" mean in AgentLoop? "POLISH mode" is an operational state where AgentLoop continues iterating even after a PASS verdict. It keeps cycling until the independent critic returns a SHIP verdict, indicating the work has met a higher, production-ready standard defined in your guidelines, allowing for automated code refinement.