Agent Looper

Autonomous AI agent execution with iterative planning. Runs AI agents (like Claude CLI) in a continuous loop, enabling autonomous work through a planning document.

Features

• Autonomous Execution: Run AI agents in a continuous loop
• Plan-Driven: Agent works through a markdown planning document
• Real-Time Controls: Pause, kill, add notes, or quit at any time
• Token Tracking: Monitor token usage and costs across iterations
• Web UI: Remote monitoring and control via browser
• Cross-Platform: Works on Linux, macOS, and Windows
• Zero Runtime Dependencies: Pure Node.js implementation

Installation

# Using npx (no installation required)
npx @baublet/agent-looper ./plan.md

# Global installation
npm install -g @baublet/agent-looper

# Then run with any of these commands:
agent-looper ./plan.md
agentLooper ./plan.md
al ./plan.md

Quick Start

1. Create a plan document (or use --example to see the format):

# My Project Plan

## Overview
Building a new feature for the application.

## Tasks
- [ ] Research existing implementation
- [ ] Design the solution
- [ ] Implement core functionality
- [ ] Write tests
- [ ] Update documentation

## Completed
<!-- Tasks will be moved here -->

## Notes
- Important context goes here

2. Start the agent loop:

agent-looper ./my-plan.md

3. Use controls during execution:
   • p - Pause/Resume the loop
   • k - Kill current agent (starts next iteration)
   • n - Add a note for the next iteration
   • q - Quit the loop

Usage

agent-looper <plan-document>

USAGE:
    agent-looper <plan-document>
    agent-looper --plan <plan-document>
    agent-looper --example

OPTIONS:
    -y, --yes               Skip confirmation prompt
    -q, --quiet             Suppress non-essential output (errors and final stats still shown)
    --dry-run               Show configuration and exit without running
    --max-iterations <n>    Maximum iterations to run (0 = unlimited)
    --max-time <minutes>    Max time per iteration before considered failed (default: 60)
    --planning-cmd <cmd>    Command for planning mode (default: claude)
    --agent-cmd <cmd>       Command for agent execution
    --log <file>            Log file path (default: agentLoop.log)
    --web-ui <secret>       Enable web UI with the given secret
    --completion-doc <file> Path to completion criteria document for auto-quit
    --resume                Resume from saved state if available
    --example               Show example plan structure
    --version, -v           Show version
    --help, -h              Show this help message

EXAMPLES:
    agent-looper ./project-plan.md
    agent-looper -y ./plan.md
    agent-looper --dry-run ./plan.md
    agent-looper --agent-cmd "claude -p --model opus" ./plan.md
    agent-looper --max-iterations 5 ./plan.md
    agent-looper --max-time 30 ./plan.md
    agent-looper --completion-doc ./done-criteria.md ./plan.md
    agent-looper --resume ./plan.md

How It Works

Each iteration of the loop:

1. Orient: Agent reads the plan and understands current state
2. Refine: Agent updates the plan, promotes backlog items, removes stale tasks
3. Execute: Agent completes one task fully
4. Review: Agent verifies work and makes improvements
5. Update: Agent records progress and prepares for next iteration

The human operator can:

• Watch progress in real-time
• Pause to review work
• Inject notes/guidance for the next iteration
• Kill stuck iterations
• Quit when satisfied

Plan Document Format

The plan document is a markdown file that serves as the agent's source of truth:

# Project Name

## Overview
What you're building and why.

## Goals
1. Primary objective
2. Secondary objectives

## Current Work
- [ ] Active task 1
- [ ] Active task 2

## Backlog
- [ ] Future task 1
- [ ] Future task 2

## Completed
- [x] Done task (moved here with notes)

## Notes
- Context and decisions
- Links and references

Configuration File

Create a .agentlooperrc file in your project directory or home directory to set default options:

{
  "yes": true,
  "maxIterations": 10,
  "maxTime": 30,
  "planningCmd": "claude",
  "agentCmd": "claude -p --model opus --verbose --output-format json",
  "log": "agent.log",
  "webUi": "mysecret"
}

Configuration precedence:

1. CLI arguments (highest priority)
2. .agentlooperrc in current directory
3. .agentlooperrc in home directory
4. Built-in defaults (lowest priority)

Available options: | Config Key | CLI Flag | Description | |------------|----------|-------------| | yes | -y, --yes | Skip confirmation prompt | | quiet | -q, --quiet | Suppress non-essential output | | maxIterations | --max-iterations | Maximum iterations (0 = unlimited) | | maxTime | --max-time | Max minutes per iteration (default: 60) | | planningCmd | --planning-cmd | Command for interactive planning | | agentCmd | --agent-cmd | Command for agent execution | | log | --log | Log file path | | webUi | --web-ui | Secret for web UI access |

See examples/agentlooperrc.example.json for a complete example.

Custom Agent Commands

By default, Agent Looper uses the Claude CLI. You can use any compatible agent:

# Use Claude with specific model
agent-looper --agent-cmd "claude -p --model opus" ./plan.md

# Use with additional flags
agent-looper --agent-cmd "claude -p --verbose --output-format json" ./plan.md

The agent command receives the full prompt (plan document + instructions) as an argument.

Interactive Planning

Create a new plan interactively before starting the loop:

agent-looper --plan ./new-project.md

This launches the planning command (default: claude) to help you create the initial plan.

Session Persistence

Agent Looper saves session state after each iteration, enabling resumption of interrupted loops:

# Start a loop
agent-looper ./plan.md

# (interrupted by Ctrl+C or quit)

# Resume from where you left off
agent-looper --resume ./plan.md

State includes:

• Iteration count and success/failure stats
• Total duration and per-iteration timings
• Token usage and cost estimates
• Peak memory usage

State file location: .agentlooper.<plan-name>.state.json adjacent to your plan document.

To start fresh (ignoring saved state), omit the --resume flag.

Token Usage & Cost Tracking

Agent Looper tracks token usage and estimated costs across iterations:

Stats: Iterations: 5 | Success: 5 | Failed: 0 | Time: 12m 34s | Tokens: 125.3K ($2.45)

Token tracking requires --output-format json in the agent command (included by default).

Log Files

All agent output is logged to agentLoop.log (or custom path with --log):

# View logs in real-time
tail -f agentLoop.log

# Custom log path
agent-looper --log ./logs/session.log ./plan.md

Automated Completion Detection

Use --completion-doc to specify a completion criteria document. After each successful iteration, a separate AI evaluation checks if the project meets the completion criteria:

agent-looper --completion-doc ./done-when.md ./plan.md

Completion criteria document example (done-when.md):

# Done When

1. All tests pass
2. Documentation is updated
3. No TODO items remain in the plan
4. Build generates no errors

See examples/completion-criteria.md for a more detailed example.

How it works:

1. After each successful agent iteration, the completion evaluator runs
2. It reads both the plan document and completion criteria
3. If criteria are NOT met: logs why and continues to the next iteration
4. If criteria ARE met: creates PLAN.completionSummary.md and exits the loop

Token tracking: Completion evaluator tokens are tracked separately and shown in final stats:

Completion Evaluator:
  Tokens: 5.2K (in: 4.8K, out: 0.4K)
  Cost:   $0.12

Combined Totals:
  Tokens: 130.5K
  Cost:   $2.57

Web UI

Enable a web-based dashboard for remote monitoring and control:

agent-looper --web-ui mysecrettoken ./plan.md

When started, the CLI displays a URL like:

Web UI: http://127.0.0.1:54321/?secret=mysecrettoken

The web UI provides:

• Real-time Statistics: Iteration count, success/failure rates, duration, token usage, and costs
• Live Log Streaming: Watch agent output in real-time via Server-Sent Events
• JSON Log Explorer: Browse and inspect JSON log entries with smart formatting for dates, tokens, costs, and large text
• Remote Controls: Pause/resume, kill current agent, add notes, and quit
• Connection Status: Shows if the browser is connected to the server

Security: The secret token must be in the URL query parameter. Requests without the correct secret return 404. The server only binds to localhost (127.0.0.1).

Requirements

• Node.js 18+
• Claude CLI (or compatible agent command)

Development

# Clone the repository
git clone https://github.com/baublet/agent-looper.git
cd agent-looper

# Install dependencies
npm install

# Install pre-commit hook (recommended)
cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
# Or symlink: ln -sf ../../scripts/pre-commit .git/hooks/pre-commit

# Build
npm run build

# Type check
npm run typecheck

# Run locally
node dist/cli.js --help

Build Artifacts

Build artifacts in dist/ are version controlled. The pre-commit hook automatically:

1. Runs the build (npm run build)
2. Stages the built files (git add dist/)

This ensures NPM packages are published with pre-built artifacts and no build step is required during npm publish.

You can run type checking manually with npm run typecheck.

Versioning

This project follows Semantic Versioning (SemVer):

• MAJOR (1.0.0 → 2.0.0): Breaking changes
• MINOR (1.1.0 → 1.2.0): New features, backwards compatible
• PATCH (1.1.0 → 1.1.1): Bug fixes, backwards compatible

Pre-release versions use suffixes like 1.2.0-beta.1 or 1.2.0-rc.1.

Releasing

Prerequisites

1. npm authentication: Run npm login or set NPM_TOKEN
2. Clean working directory: All changes committed and pushed
3. Correct branch: Release versions require main/master branch

Release Process

# 1. Ensure tests pass
npm run test:all

# 2. Update version in package.json manually
# Edit package.json to set the new version number

# 3. Update CHANGELOG.md
# Move items from [Unreleased] to new version section

# 4. Commit version bump
git add package.json CHANGELOG.md
git commit -m "Release v1.2.0"
git tag v1.2.0

# 5. Push to GitHub
git push && git push --tags

# 6. Publish to NPM (runs all checks automatically)
npm run publish:npm

Publish Script

The publish script (npm run publish:npm) automatically:

1. ✅ Verifies npm authentication
2. ✅ Runs the build
3. ✅ Checks for uncommitted changes
4. ✅ Validates branch (release versions require main/master)
5. ✅ Publishes to NPM

Use npm run publish:check to do a dry run without publishing.

Pre-release Versions

Pre-release versions (e.g., 1.2.0-beta.1) can be published from any branch:

# Edit package.json to set version like "1.2.0-beta.1"
git add package.json
git commit -m "Pre-release v1.2.0-beta.1"
npm run publish:npm

Verifying the Release

After publishing:

# Check NPM
npm view @baublet/agent-looper

# Test installation
npx @baublet/agent-looper@latest --version

Architecture

src/
├── cli.js           # CLI entry point
├── main.js          # Library exports
└── lib/
    ├── args.js      # Argument parsing
    ├── colors.js    # Terminal colors
    ├── completion.js # Completion evaluation
    ├── config.js    # Configuration file loading
    ├── format.js    # Formatting utilities
    ├── logger.js    # Logging infrastructure
    ├── loop.js      # Main agent loop
    ├── notes.js     # Notes input screen
    ├── prompt.js    # Prompt generation
    ├── spinner.js   # Spinner animation
    ├── state.js     # Session state persistence
    ├── status.js    # Status display
    ├── terminal.js  # Terminal control
    ├── tokens.js    # Token extraction
    └── webui/
        └── server.js  # Web UI HTTP server

License

MIT