ALPF

Agentic Loop with Promise Fulfilment. A deterministic agent framework that executes tasks iteratively until a completion condition (promise) is verified.

Why ALPF?

• Promise-driven completion: Define what success looks like, loop until verified
• Progress detection: Automatic identification of stalled tasks prevents infinite loops
• File-locked state: Multiple agents work safely on the same project simultaneously
• Bounded execution: Max attempts, timeouts, and no-progress thresholds prevent resource exhaustion
• Append-only history: Immutable JSONL logs for auditing and debugging
• Dynamic task pivoting: Update executor strategy mid-loop without stopping
• Cross-platform: Single Go binary, no external dependencies

Installation

From source

git clone https://github.com/codehakase/alpf.git
cd alpf
go build -o alpf ./cmd/alpf
mv alpf /usr/local/bin/ # or add to your PATH

With go install

go install github.com/codehakase/alpf/cmd/alpf@latest

Quick Start

# Initialize in your project
cd your-project
alpf init # Creates .alpf/config.json

# Configure your promise and task in .alpf/config.json
# (see Configuration Reference below)

# Start the loop
alpf start

# Monitor progress in another terminal
alpf status
alpf history --limit 5

CLI Commands

Command	Description
alpf init	Create .alpf/ directory and default config
alpf start	Run the execution loop until promise fulfilled or max attempts
alpf status	Query current execution state
alpf history [--limit N]	Show attempt history
alpf rollback --attempt N	Revert to a previous attempt
alpf update-task --config <json>	Change executor mid-loop
alpf stop	Stop execution gracefully
alpf mcp serve	Start MCP server for Claude Code integration

Claude Code Integration

ALPF exposes an MCP (Model Context Protocol) server for integration with Claude Code and other AI tools.

Setup

1. Install alpf globally:

   go install github.com/codehakase/alpf/cmd/alpf@latest

2. Add to ~/.claude.json:

   {
     "mcpServers": {
       "alpf": {
         "command": "/path/to/go/bin/alpf",
         "args": ["mcp", "serve"],
         "type": "stdio"
       }
     }
   }

3. Restart Claude Code

Available Tools

Tool	Description
alpf_status	Get current execution status and progress metrics
alpf_start	Start the execution loop
alpf_history	Get attempt history (optional limit param)
alpf_rollback	Rollback to a previous attempt
alpf_get_promise	Get the promise definition
alpf_update_task	Update task specification mid-execution
alpf_stop	Stop execution gracefully

All tools accept an optional project_path parameter. If omitted, ALPF auto-detects the project from the current working directory.

Example Usage in Claude Code

> What's the alpf status?
> Start the alpf loop
> Show me the last 5 attempts
> Rollback to attempt 3

Configuration

File: .alpf/config.json

{
  "agent_id": "my-agent",
  "promise": {
    "description": "Tests pass",
    "validator": {
      "type": "shell",
      "config": {
        "command": "npm test"
      }
    }
  },
  "task_spec": {
    "description": "Build and test",
    "executor": {
      "type": "shell",
      "config": {
        "command": "npm run build && npm test"
      }
    }
  },
  "retry_strategy": {
    "max_attempts": 10,
    "backoff": {
      "type": "exponential",
      "initial_delay_ms": 1000,
      "max_delay_ms": 30000,
      "multiplier": 2
    }
  },
  "bounds": {
    "max_runtime_seconds": 600,
    "max_total_attempts": 50,
    "fail_if_no_progress_after_n_attempts": 3
  }
}

Promise Validators

Type	Description	Example
shell	Run command, success on exit 0	npm test
file_exists	Check if file exists	dist/index.js
api_check	Check HTTP endpoint	https://api.example.com/health
custom	Custom validation function	validateOutput

Task Executors

Type	Description	Example
shell	Run shell command	npm run build
subprocess	Run external program	python train.py
api_call	Make HTTP request	POST /deploy

Backoff Types

• exponential: Delay doubles each attempt (1s → 2s → 4s → 8s)
• linear: Delay increases linearly (1s → 2s → 3s → 4s)
• fixed: Same delay between attempts (1s → 1s → 1s)

State Management

ALPF tracks execution in .alpf/:

.alpf/
├── config.json          # Configuration (edit manually)
├── state.json           # Current state (locked during writes)
└── history.jsonl        # Append-only attempt log

state.json:

{
  "execution_state": {
    "current_attempt": 3,
    "status": "running",
    "promise_fulfilled": false
  },
  "last_attempt_result": {
    "task_output": "...",
    "promise_check_result": false,
    "state_changed": true,
    "execution_time_ms": 2105
  }
}

history.jsonl:

{"attempt":1,"timestamp":"2026-01-06T14:32:05Z","task_output":"...","promise_check_result":false,"state_changed":true}
{"attempt":2,"timestamp":"2026-01-06T14:32:06Z","task_output":"...","promise_check_result":false,"state_changed":true}

Examples

Build until tests pass

{
  "promise": {
    "description": "Tests pass",
    "validator": {"type": "shell", "config": {"command": "npm test"}}
  },
  "task_spec": {
    "executor": {"type": "shell", "config": {"command": "npm run build && npm test"}}
  },
  "retry_strategy": {"max_attempts": 15, "backoff": {"type": "exponential", "initial_delay_ms": 500, "max_delay_ms": 10000}}
}

Deploy until health check passes

{
  "promise": {
    "description": "API health check returns 200",
    "validator": {"type": "api_check", "config": {"endpoint": "https://api.example.com/health", "expected_status": 200}}
  },
  "task_spec": {
    "executor": {"type": "shell", "config": {"command": "docker build -t app . && docker run app"}}
  },
  "bounds": {"max_attempts": 20, "fail_if_no_progress_after_n_attempts": 5}
}

Blockchain transaction until confirmed

{
  "promise": {
    "description": "Transaction confirmed on-chain",
    "validator": {"type": "custom", "config": {"function": "checkTransactionConfirmed"}}
  },
  "task_spec": {
    "executor": {"type": "subprocess", "config": {"command": "node", "args": ["submit-transaction.js"]}}
  },
  "retry_strategy": {"max_attempts": 30, "backoff": {"type": "linear", "initial_delay_ms": 2000, "max_delay_ms": 15000}}
}

Parallel Agents

ALPF uses POSIX file locks for safe concurrent access:

# Terminal 1: Agent A
alpf start --project-path ./shared-project

# Terminal 2: Agent B (safe to run in parallel)
alpf status --project-path ./shared-project
alpf update-task --config '{"command":"faster-build"}' --project-path ./shared-project

Multiple agents won't corrupt state because only one writer acquires the exclusive lock at a time.

Agent Working Memory (Complex Tasks)

For multi-phase tasks, use .alpf_planning/ for agent notes:

.alpf_planning/
├── task_plan.md         # Phases, goals, decisions
├── notes.md             # Research findings
└── progress.md          # Detailed execution log

Agents read these before decisions to stay focused on original goals.

Requirements

• Go 1.25.4 or later
• POSIX-compliant filesystem (for file locking)

License

MIT