aloop 0.1.2

One loop is all you need.

aloop is an AI agent built on a single, unified loop. Planning, parallel sub-agents, self-verification — everything folds into the same loop, chosen autonomously by the agent itself, not by a hardcoded workflow. Simple architecture, emergent capability.

Installation

Prerequisites: Python 3.12+.

pip install aloop

Or install from source (for development):

git clone https://github.com/luohaha/aloop.git
cd aloop
./scripts/bootstrap.sh   # requires uv

Quick Start

1. Configure Models

On first run, ~/.aloop/models.yaml is created with a template. Edit it to add your provider and API key:

models:
  openai/gpt-4o:
    api_key: sk-...

  anthropic/claude-3-5-sonnet-20241022:
    api_key: sk-ant-...

  ollama/llama2:
    api_base: http://localhost:11434

default: openai/gpt-4o

See LiteLLM Providers for the full list.

2. Run

# Interactive mode
aloop

# Single task (returns raw result)
aloop --task "Calculate 123 * 456"

# Resume last session
aloop --resume

# Resume specific session (ID prefix)
aloop --resume a1b2c3d4

CLI Reference

Interactive Commands

Slash Commands

Keyboard Shortcuts

How It Works

Agent loop: The agent follows a Think-Act-Observe cycle. It reasons about the task, selects a tool, observes the result, and repeats until it has an answer. Planning, sub-agent dispatch, and tool use all happen inside this single loop.

Ralph verification: For single tasks (--task), an outer loop verifies the agent's answer against the original task. If incomplete, feedback is injected and the agent loop re-enters. Configurable via RALPH_LOOP_MAX_ITERATIONS (default: 3).

Memory compression: When context grows past a token threshold, older messages are compressed via LLM summarization. Recent messages are kept at full fidelity. Strategies: sliding_window (default), selective, deletion.

Session persistence: Conversations are saved as YAML files under ~/.aloop/sessions/. Resume with --resume or /resume.

Features

• AGENTS.md support: Project-specific instructions guide the agent automatically (see AGENTS.md Guide)
• Memory management: Automatic compression and persistence of conversation history
• Ralph verification: Self-verification loop for single tasks
• Tool-rich: 18+ specialized tools for file ops, code navigation, web search, and more

Tools

Project Structure

aloop/
├── main.py                 # Entry point (argparse)
├── cli.py                  # CLI wrapper (`aloop` entry point)
├── interactive.py          # Interactive session, model setup, TUI
├── config.py               # Runtime config (~/.aloop/config)
├── agent/
│   ├── base.py             # BaseAgent (ReAct + Ralph loops)
│   ├── agent.py            # LoopAgent
│   ├── verification.py     # LLMVerifier for Ralph loop
│   ├── context.py          # Context injection (cwd, platform, date)
│   ├── tool_executor.py    # Tool execution engine
│   └── todo.py             # Todo list data structure
├── llm/
│   ├── litellm_adapter.py  # LiteLLM adapter (100+ providers)
│   ├── model_manager.py    # Model config from ~/.aloop/models.yaml
│   ├── retry.py            # Retry with exponential backoff
│   └── message_types.py    # LLMMessage, LLMResponse, ToolCall
├── memory/
│   ├── manager.py          # Memory orchestrator + persistence
│   ├── compressor.py       # LLM-driven compression
│   ├── short_term.py       # Short-term memory (sliding window)
│   ├── token_tracker.py    # Token counting + cost tracking
│   ├── types.py            # Core data structures
│   └── store/
│       └── yaml_file_memory_store.py  # YAML session persistence
├── tools/                  # 18 tool implementations
├── utils/
│   ├── tui/                # TUI components (input, themes, status bar)
│   ├── logger.py           # Logging setup
│   └── model_pricing.py    # Model pricing data
├── docs/                   # Documentation
├── test/                   # Tests
├── scripts/                # Dev scripts (bootstrap.sh, dev.sh)
└── rfc/                    # RFC design documents

Configuration

Runtime settings live in ~/.aloop/config (auto-created). Key settings:

See Configuration Guide for all settings.

Documentation

• Configuration -- model setup, runtime settings, custom endpoints
• Examples -- usage patterns and programmatic API
• Memory Management -- compression, persistence, token tracking
• Extending -- adding tools, agents, LLM providers
• Packaging -- building, publishing, Docker

License

MIT License