Architecture
AgentLoop uses a layered architecture that coordinates multiple AI agents through an intelligent orchestration system. This page explains how the components work together.
System Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ AgentLoop CLI │
│ Interactive Mode / Query Mode / Daemon │
└─────────────────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ DAG Task Scheduler │ │
│ │ Manages dependencies, parallelism, and execution order │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Behavior Tree Engine │ │
│ │ Decision logic, validation layers, AI management │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────┬───────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ Product Manager │ │ Engineer(s) │ │ QA Tester │
│ Agent │ │ Agents │ │ Agent │
└───────────────────┘ └───────────────────┘ └───────────────────┘Components
CLI Layer
The CLI layer provides three modes of interaction:
| Mode | Command | Description |
|---|---|---|
| Interactive | agentloop | Full TUI with conversational interface |
| Query | agentloop query "..." | Single query/response |
| Daemon | /daemon start | Background service |
Orchestrator
The orchestrator is the central coordination layer. It contains two main subsystems:
DAG Task Scheduler
- Manages task dependencies as a Directed Acyclic Graph
- Determines optimal execution order
- Maximizes parallelism while respecting prerequisites
- Handles complex dependency chains
Behavior Tree Engine
- Configurable decision-making logic for agents
- Validation layers for quality gates
- Adaptive agent behavior management
- Industry-standard behavior tree patterns
Specialized Agents
Each agent has a specific role in the development workflow:
| Agent | Responsibilities |
|---|---|
| Product Manager | Task breakdown, AGILE planning, user stories |
| Engineer | Code changes, git operations, PR creation |
| QA Tester | Test execution, validation, issue reporting |
| Code Analyzer | Architecture analysis, dependency understanding |
Execution Flow
How It Works
-
Task Creation - Define tasks manually, generate from descriptions using the PM agent, or sync from Jira
-
DAG Scheduling - The orchestrator analyzes task dependencies and creates an optimal execution plan
-
Parallel Execution - Multiple engineer agents work simultaneously on independent tasks
-
Isolated Environments - Each agent can work in its own git worktree or container sandbox
-
Quality Gates - QA agents validate completed work before marking tasks done
-
Continuous Loop - The orchestrator monitors progress and handles failures with self-healing recovery
Parallel Execution
AgentLoop supports true parallel execution through two mechanisms:
Git Worktrees
Each agent can work in an isolated git worktree:
Main Repository (.git)
│
├── Main Working Directory (main branch)
│
├── .worktrees/
│ ├── feature-auth/ ← Agent 1 working here
│ │ └── (branch: feature/auth)
│ │
│ ├── feature-api/ ← Agent 2 working here
│ │ └── (branch: feature/api)
│ │
│ └── bugfix-login/ ← Agent 3 working here
│ └── (branch: bugfix/login)See Git Worktrees for details.
Container Sandboxing
Optional Podman-based isolation for secure agent execution:
┌─────────────────────────────────────────────────────┐
│ Host System │
│ ┌───────────────────────────────────────────────┐ │
│ │ Podman Container │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ Engineer Agent │ │ │
│ │ │ • Restricted filesystem access │ │ │
│ │ │ • Network isolation │ │ │
│ │ │ • Resource limits (CPU, memory) │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘See Container Sandboxing for details.
Kanban Integration
All task management flows through the kanban board:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Kanban Board │
│ ┌─────────┐ ┌─────────────┐ ┌────────┐ ┌──────┐ ┌─────────┐ │
│ │ Todo │ │ In Progress │ │ Review │ │ Done │ │ Blocked │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ Task 1 │ │ Task 3 │ │ Task 5 │ │Task 7│ │ Task 9 │ │
│ │ Task 2 │ │ Task 4 │ │ Task 6 │ │Task 8│ │ │ │
│ └─────────┘ └─────────────┘ └────────┘ └──────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘See Kanban Board for details.
External Integrations
AgentLoop connects to external services for enhanced functionality:
┌─────────────────────────────────────────────────────────────────────────────┐
│ External Integrations │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Jira │ │ GitHub │ │ MCP │ │
│ │ Sync │ │ PRs │ │ Servers │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘| Integration | Purpose |
|---|---|
| Jira | Bidirectional task sync, sprint management |
| GitHub | PR creation, branch management |
| MCP | Model Context Protocol for external tools |
See Integrations for details.
Self-Healing & Recovery
AgentLoop includes built-in recovery mechanisms:
- Orphaned task detection - Automatically identifies and recovers abandoned tasks
- Process health monitoring - Cleans up stale executions
- Race condition prevention - Ensures task state consistency
- Crash recovery - Resumes from interruptions
The self-healing system runs automatically. You don’t need to configure it, but you can check its status with /orchestrator status.