Agent Loop

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

- 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

- Node.js (for some MCP server integrations, e.g., Brave Search, Obsidian)
- Docker, Git, AWS CLI, kubectl, etc. (for full tool support)

- Linux, macOS, or Windows Subsystem for Linux (WSL)

- Anthropic API key (for Claude models)
- OpenAI API key (for GPT models)
- (Optional) Jira and Confluence API keys for those integrations

Agent Loopis 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--safeto 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).

- 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.

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

- Maximum iterations: Configurable hard limit (default: 20) prevents infinite loops
- Progress display: Shows current iteration count in real-time
- Configuration: Set viaMAX_ITERATIONSenv var or--max-iterationsCLI flag

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

Prevents infinite loops by detectingargument-awarepatterns:

- Same tool withidentical argumentscalled 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:

- ✅ Callingbashwith different commands (legitimate investigation) isallowed
- ❌ Callingbashwith thesame command5+ times isblocked

This prevents false positives while still catching true stuck behaviors.

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

# 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

- 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.

- CTRL+C: Interrupts the current operation and returns to the prompt (does not exit).
- CTRL+Dor typingexit/quitat 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.

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.

- Conversational AI agent powered by Anthropic Claude or OpenAI GPT
- Configurable AI provider and temperaturevia environment variables
- Pragmatic loop controlwith iteration limits and completion detection
- Tool execution with optional human confirmation (--safemode)
- Debug mode for transparency (--debug)
- Custom tools supportwith automatic discovery and display
- Visual tool differentiationwith distinct icons for built-in, MCP, and custom tools
- Modular, extensible tool system
- Functional programming style throughout
- Enhanced error handlingwith detailed diagnostic information
- Flexible configurationwith local.envfile priority
- MCP (Model Context Protocol) integration for external tool/service discovery and use

MCP (Model Context Protocol) Integration

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 byCursor AI IDE.See theCursor MCP documentationfor more details and advanced options.

{ "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 theCursor MCP documentation.

🔧 [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

SeeCreating Tools Guidefor instructions on how to create your own tools.

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

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

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

Usinguv, a much faster Python package manager:

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

For detailed instructions, seeMicrosoft's WSL installation guide

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

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

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

# 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

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

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

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 ...

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

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