Agent Loop

> An AI Agent with optional Human-in-the-Loop Safety, Model Context Protocol (MCP) integration, and beautiful, themeable CLI output

Tools

Requirements

• Python: >= 3.12
• Core Python dependencies:
  • anthropic >= 0.51.0
  • halo >= 0.0.31
  • mcp[cli] >= 1.9.2
  • openai >= 1.79.0
  • plotext >= 5.3.2
  • python-dotenv >= 1.1.0
  • requests >= 2.32.3
  • sympy >= 1.14.0
• Recommended for installation:
  • uv (for fast dependency installation)
• Optional/for full tool support:
  • Node.js (for some MCP server integrations, e.g., Brave Search, Obsidian)
  • Docker, Git, AWS CLI, kubectl, etc. (for full tool support)
• Platform:
  • Linux, macOS, or Windows Subsystem for Linux (WSL)
• API Keys (for full functionality):
  • Anthropic API key (for Claude models)
  • OpenAI API key (for GPT models)
  • (Optional) Jira and Confluence API keys for those integrations

Overview

Agent Loop is a command-line AI assistant. It leverages Anthropic's Claude or OpenAI's GPT models and a suite of powerful tools to automate, inspect, and manage your development environment—while keeping you in control with optional human confirmation for every action.

• Human-in-the-Loop: Add `--safe` to require confirmation before any tool runs.
• Functional Programming: Clean, composable, and testable code.
• DevOps Ready: Integrates with Bash, Python, Docker, Git, Kubernetes, AWS, and more.
• Multi-Provider: Supports both Anthropic Claude and OpenAI GPT models.
• MCP Integration: Dynamically loads and uses tools/services from any MCP-compatible server (see below).

Code Structure

• `main.py` — Main event loop and orchestration
• `cli_input.py` — Terminal input handling (CTRL+C, CTRL+Q, backspace, etc.)
• `signals.py` — Signal handling (SIGINT for interruption)
• `constants.py` — User-facing strings and help messages
• `exceptions.py` — Custom exceptions for clean exit and error handling

All components are designed for modularity, minimalism, and functional programming style.

Loop Control and Pragmatic Stopping

Agent Loop includes intelligent stopping mechanisms to prevent runaway iterations and excessive token usage:

Iteration Limits

• Maximum iterations: Configurable hard limit (default: 20) prevents infinite loops
• Progress display: Shows current iteration count in real-time
• Configuration: Set via `MAX_ITERATIONS` env var or `--max-iterations` CLI flag

Completion Detection

The agent automatically detects when a task is complete by recognizing:

• Explicit completion phrases ("task complete", "finished", "done")
• Brief responses with no further tool calls
• Agent providing summaries without requesting more actions

When completion is detected, the system prompts you to confirm before stopping, allowing you to:

• Stop: End the session if the task is truly complete
• Continue: Give the agent more iterations if additional work is needed

Repetition Detection

Prevents infinite loops by detecting argument-aware patterns:

• Same tool with identical arguments called 5+ times consecutively
• Alternating patterns with identical calls (e.g., same bash command → same file write → repeat...)
• Repeated sequences of tool calls with identical arguments

Important: The detection is argument-aware, meaning:

• ✅ Calling `bash` with different commands (legitimate investigation) is allowed
• ❌ Calling `bash` with the same command 5+ times is blocked

This prevents false positives while still catching true stuck behaviors.

When repetition is detected, the agent stops immediately with a clear explanation.

Configuration

# In ~/.config/agent-loop/.env or local .env
MAX_ITERATIONS=20              # Maximum thinking cycles
PROMPT_ON_COMPLETION=true      # Ask before stopping on completion

# Via CLI
agent-loop --max-iterations 50                # Override iteration limit
agent-loop --no-prompt-on-completion          # Auto-stop without prompting

System Prompt Guidance

The agent is instructed to:

• Complete requested tasks precisely, then stop
• Avoid "while I'm here" improvements
• Not add unrequested features, documentation, or tests
• Provide summaries when work is complete instead of continuing

This ensures the agent stays focused on your actual request and doesn't waste tokens on unnecessary elaboration.

Graceful Exit and Signal Handling

• CTRL+C: Interrupts the current operation and returns to the prompt (does not exit).
• CTRL+D or typing `exit`/`quit` at the prompt: Exits the application cleanly, with no traceback or error.
• Only SIGINT (CTRL+C) is handled as a signal for async safety; quit is handled at the prompt for robust, async-safe shutdown.

Async-Aware LLM Support

Agent Loop automatically supports both synchronous and asynchronous LLM functions, ensuring optimal performance and compatibility. The main event loop will call your LLM function in the most efficient way, whether it is sync or async.

Features

• Conversational AI agent powered by Anthropic Claude or OpenAI GPT
• Configurable AI provider and temperature via environment variables
• Pragmatic loop control with iteration limits and completion detection
• Tool execution with optional human confirmation (`--safe` mode)
• Debug mode for transparency (`--debug`)
• Custom tools support with automatic discovery and display
• Visual tool differentiation with distinct icons for built-in, MCP, and custom tools
• Modular, extensible tool system
• Functional programming style throughout
• Enhanced error handling with detailed diagnostic information
• Flexible configuration with local `.env` file priority
• MCP (Model Context Protocol) integration for external tool/service discovery and use

MCP (Model Context Protocol) Integration

New in v2.0!

Agent Loop can now connect to any number of MCP-compatible servers, dynamically discovering and using their services as tools. This means you can:

• Add new capabilities (search, knowledge, automation, etc.) by simply running or configuring an MCP server.
• Use tools from remote or local MCP servers as if they were built-in.
• Aggregate services from multiple sources (e.g., Brave Search, Obsidian, custom servers) in one agent.

> **ℹ️ The MCP server configuration format is identical to that used by Cursor AI IDE.**

> See the Cursor MCP documentation for more details and advanced options.

How it works

• On startup, Agent Loop reads your MCP server configuration from `~/.config/agent-loop/mcp.json`.
• For each server, it starts a session and lists available services.
• Each service is registered as a tool (named `-`) and can be called by the agent or user.
• All MCP tools are available alongside built-in tools.

Example MCP config

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "..." }
    },
    "mcp-obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian", "/path/to/obsidian-vault/"]
    }
  }
}

• Place this file at `~/.config/agent-loop/mcp.json`.
• Each server can be a local or remote MCP-compatible service.
• All services/tools from these servers will be available in your agent session.
• For more details, see the Cursor MCP documentation.

Available Tools

Agent Loop comes with built-in tools and supports custom tools. The application automatically distinguishes between different tool types with visual indicators:

• 🛠️ Built-in Tools: Core application tools
• 🔌 MCP Tools: External tools from Model Context Protocol servers
• 🔧 Custom Tools: User-defined tools loaded from `~/.config/agent-loop/tools/`

On startup, Agent Loop will display any custom tools that have been loaded:

🔧 [Custom Tools] Loaded 2 custom tool(s) from ~/.config/agent-loop/tools:
  • hello (hello.py) - Returns a friendly greeting
  • my_tool (my_tool.py) - Custom automation tool

See Creating Tools Guide for instructions on how to create your own tools.

Installation

Option 1: Using the installation script (Recommended)

1. Download the installation package:

git clone https://github.com/your-org/agent-loop.git
   cd agent-loop

2. Run the installation script:

./install.sh

This script will:

3. Add to your PATH (if needed):

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
   source ~/.bashrc

Option 2: Manual installation

1. Clone the repository:

git clone https://github.com/your-org/agent-loop.git
   cd agent-loop

2. Install dependencies:

Using uv, a much faster Python package manager:

uv pip install -r requirements.txt

If you don't have uv installed, you can install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Uninstalling

To uninstall Agent Loop, simply run:

./install.sh uninstall

This will remove the command wrapper and the virtual environment.

Windows Subsystem for Linux (WSL) Installation

Agent Loop works great on Windows through WSL. Here's how to set it up:

1. Install WSL if you don't have it already:

wsl --install

2. Install Agent Loop in WSL:

git clone https://github.com/your-org/agent-loop.git
     cd agent-loop
     ./install.sh

3. Configuration in WSL:

mkdir -p ~/.config/agent-loop

nano ~/.config/agent-loop/.env

nano ~/.config/agent-loop/SYSTEM_PROMPT.txt

4. WSL-specific considerations:

Configuration

API Keys and Environment Variables

Create a `.env` file in the `~/.config/agent-loop` directory with your API keys and other configuration:

# Create the config directory if it doesn't exist
mkdir -p ~/.config/agent-loop

# Create your .env file
nano ~/.config/agent-loop/.env

You can also create a local `.env` file in your project directory, which will take priority over the global configuration.

You can use the `.env.example` file from the source repository as a template. At minimum, include one of these API keys:

# AI Configuration
AI_PROVIDER=anthropic  # Choose: anthropic (default) or openai
AI_TEMPERATURE=0.7     # Model temperature: 0.0-2.0 (default: 0.7)

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-sonnet-4-20250514  # Optional, defaults to claude-3-7-sonnet-latest

# OpenAI
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o  # Optional, defaults to gpt-4o

# Jira (Optional)
JIRA_BASE_URL=your_jira_instance_url
JIRA_EMAIL=your_jira_email
JIRA_API_TOKEN=your_jira_api_token

# Confluence (Optional)
CONFLUENCE_BASE_URL=your_confluence_instance_url
CONFLUENCE_EMAIL=your_confluence_email
CONFLUENCE_API_TOKEN=your_confluence_api_token

Configuration Priority:

• Local `.env` file in your current directory (highest priority)
• Global `.env` file in `~/.config/agent-loop/` (fallback)

AI Provider Selection:

• Set `AI_PROVIDER=anthropic` to use Claude models (default)
• Set `AI_PROVIDER=openai` to use GPT models
• If the preferred provider's API key is missing, the application will automatically fall back to the available provider

Temperature Control:

• `AI_TEMPERATURE` controls response creativity and randomness (0.0 = deterministic, 1.0 = creative)
• Valid range: 0.0 to 2.0
• Default: 0.7 (balanced)

Custom System Prompt

You can customize the system prompt by creating a `SYSTEM_PROMPT.txt` file in the same directory:

nano ~/.config/agent-loop/SYSTEM_PROMPT.txt

This allows you to give specific instructions or personality to the assistant. If this file doesn't exist, the default system prompt will be used.

MCP Server Configuration

To enable MCP integration, create a file at `~/.config/agent-loop/mcp.json` as shown above. Each server entry should specify the command, arguments, and any required environment variables. All services from these servers will be available as tools in your agent session.

Usage

Basic

agent-loop

Model Selection

agent-loop --model gpt-4o

or

agent-loop --model claude-3-7-sonnet-latest

Safe Mode (Human Confirmation)

agent-loop --safe

• You will be shown each command and asked to confirm before execution.

Debug Mode

agent-loop --debug

• Prints tool input/output for transparency.

Combined

agent-loop --safe --debug

Example Session

dev@agent-loop:~$ agent-loop --safe
> List all Docker containers
Agent: I will use the docker tool to list all containers.
[CONFIRMATION REQUIRED]
Tool: docker
Description: Run Docker CLI commands
Input: {'args': 'ps -a'}
Do you want to execute this command? [y/N]: y
STDOUT:
CONTAINER ID   IMAGE   ...

✨ Beautiful, Themeable CLI Output

Agent Loop uses Rich to render all agent replies and notifications in the terminal. By default, all agent answers are formatted in Markdown and rendered with color, style, and structure for maximum readability.

• Default: Answers are rendered as Markdown (headings, lists, code blocks, etc.)
• Theming: Colors and styles are fully customizable via a JSON theme file
• Plain Text Mode: Use `--simple-text` or `-s` to disable Rich/Markdown and get pure ASCII output (great for piping or minimal terminals)

Example (Markdown Output)

💬 Agent:
# Docker Containers

| CONTAINER ID | IMAGE | STATUS |
|--------------|-------|--------|
| 123abc       | nginx | Up     |
| ...          | ...   | ...    |

Example (Plain Text Output)

💬 Agent:
Docker Containers
----------------
CONTAINER ID   IMAGE   STATUS
123abc         nginx   Up
...            ...     ...

🎨 Customizing the Theme

You can fully customize the CLI appearance by editing the theme file:

• Location: `~/.config/agent-loop/theme.json`
• Format: JSON mapping style names to Rich style strings
• Fallback: If the file is missing or invalid, a beautiful default theme is used

Example `theme.json`:

{
  "agent.reply": "bold cyan",
  "agent.tool": "bold magenta",
  "agent.confirm": "bold yellow",
  "agent.error": "bold red",
  "agent.info": "dim white"
}

Change colors, add emphasis, or create your own style! See the Rich style guide for options.

🚀 CLI Flags

🛠️ Creating Your Own Tools

Agent Loop is fully extensible! You can add your own tools in minutes—no need to modify the core code.

• Drop-in Python modules (pure functions, functional programming style)
• Auto-discovered: Just place your `.py` file in `agent_loop/tools/` (built-in) or `~/.config/agent-loop/tools/` (user tools)
• No extra dependencies for user tools—see the policy in the guide

👉 See the full guide: CREATING_TOOLS.md

License

This project is licensed under the GNU Affero General Public License v3.0,

with additional terms prohibiting commercial use and requiring attribution.

See LICENSE for full details.