Overview

AgentLoop is an autonomous agent orchestrator that coordinates multiple AI agents working together to complete complex software development tasks. Specialized agents analyze, implement, and test your code—all managed through an intelligent workflow with full human oversight.

Installation

Global Installation (Recommended)

npm install -g @trygentic/agentloop

Local Installation

npm install @trygentic/agentloop

Run Without Installing

npx @trygentic/agentloop

Quick Start

# Start interactive mode
agentloop

# Run the orchestrator
agentloop orchestrator

# Send a single query
agentloop query "Analyze the architecture of this project"

Interacting with AgentLoop

In interactive mode, you can communicate with agents using natural language—just type your message and press Enter. No slash commands required for conversations. AgentLoop uses tool calls behind the scenes to update the kanban board, manage tasks and dependencies in the DAG, and delegate work to specialized agents like Engineer and QA.

> Break down "user authentication" into tasks and add them to the board
> What's the status of task 5? Mark it as in-progress
> Have the engineer agent implement the login API endpoint
> Ask the QA agent to test the new authentication flow
> Add a dependency so task 3 must complete before task 7
> Move all completed tasks to done and show me the kanban board

Slash commands (like /orchestrator run or /tasks) are available for system operations, but day-to-day interaction—including task management, agent coordination, and board updates—is conversational.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              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        │
│                   │ │                   │ │                   │
│ • Task breakdown  │ │ • Code changes    │ │ • Test execution  │
│ • AGILE planning  │ │ • Git operations  │ │ • Validation      │
│ • User stories    │ │ • PR creation     │ │ • Issue reporting │
└───────────────────┘ └───────────────────┘ └───────────────────┘
            │                     │                    │
            │         ┌───────────┴───────────┐        │
            │         ▼                       ▼        │
            │  ┌─────────────┐       ┌─────────────┐   │
            │  │  Worktree 1 │       │  Worktree 2 │   │
            │  │  (branch-a) │       │  (branch-b) │   │
            │  └─────────────┘       └─────────────┘   │
            │                                          │
            └──────────────────┬───────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           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│  │         │            │
│  └─────────┘  └─────────────┘  └────────┘  └──────┘  └─────────┘            │
└─────────────────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                        External Integrations                                │
│         ┌──────────┐    ┌──────────┐    ┌──────────┐                        │
│         │   Jira   │    │  GitHub  │    │   MCP    │                        │
│         │   Sync   │    │   PRs    │    │ Servers  │                        │
│         └──────────┘    └──────────┘    └──────────┘                        │
└─────────────────────────────────────────────────────────────────────────────┘

How It Works

1. Task Creation - Define tasks manually, generate them from descriptions using the Product Manager agent, or sync from Jira
2. DAG Scheduling - The orchestrator analyzes task dependencies and creates an optimal execution plan
3. Parallel Execution - Multiple engineer agents work simultaneously on independent tasks
4. Isolated Environments - Each agent can work in its own git worktree or container sandbox
5. Quality Gates - QA agents validate completed work before marking tasks done
6. Continuous Loop - The orchestrator monitors progress and handles failures with self-healing recovery

Features

Multi-Agent Orchestration

AgentLoop coordinates multiple specialized AI agents that work together seamlessly:

• Orchestrator Agent - Manages overall workflow, delegates tasks, and ensures smooth handoffs between agents
• Product Manager Agent - Breaks down project descriptions into AGILE tasks, user stories, and sprint plans
• Engineer Agent - Autonomous code implementation with proper git workflows
• QA Tester Agent - Automated testing, issue identification, and validation
• Code Analyzer Agent - Deep codebase analysis for architecture and dependency understanding

Parallel Agent Execution

Multiple engineer agents can work on different tasks simultaneously, dramatically reducing development time through true concurrency with configurable parallelism limits.

DAG-Based Task Management

Define task dependencies using a Directed Acyclic Graph (DAG) and let the orchestrator automatically determine the optimal execution order. The system maximizes parallelism while respecting prerequisites and handles complex dependency chains intelligently.

Interactive Kanban Board

Visual task management with a terminal-based kanban board showing tasks across columns: Todo, In Progress, Review, Done, and Blocked. Navigate, update, and manage tasks directly from the terminal.

Intelligent Planning

Interactive planning sessions help gather requirements, clarify scope, and generate comprehensive task breakdowns. The questionnaire system adapts based on previous answers for intelligent requirements gathering.

Self-Healing & Recovery

• Automatic detection and recovery from orphaned tasks
• Process health monitoring with cleanup of stale executions
• Race condition prevention for task state consistency
• Recovery from crashes and restarts

Behavior Tree System

Configurable, modular decision-making logic for agents using industry-standard behavior tree patterns. Includes validation layers and live AI management for adaptive agent behavior.

Jira Integration

Bidirectional synchronization with Jira Cloud:

• OAuth 2.0 and Basic Auth support
• Automatic task syncing
• AI-powered DAG planning from Jira issues
• Sprint and board management

Plugin System

Extend AgentLoop with custom agents, behavior trees, and configurations:

• Custom agent templates using markdown
• Three-layer configuration (build-time, runtime, per-project)
• MCP (Model Context Protocol) integration for external tools

Git Worktrees

AgentLoop leverages Git worktrees to enable true parallel development. Each worktree is a separate working directory linked to the same repository, allowing multiple agents to work on different branches simultaneously without conflicts.

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)

Benefits

• No Merge Conflicts During Work - Each agent has its own isolated working directory
• True Parallelism - Multiple agents can compile, test, and modify code simultaneously
• Branch Isolation - Changes in one worktree don't affect others until merged
• Efficient Storage - Worktrees share the same Git objects, minimizing disk usage

Worktree Commands

| Command | Description | |---------|-------------| | /worktrees | Open interactive worktree management view | | /worktrees list | List all active worktrees | | /worktrees status | Show worktree status summary | | /worktrees help | Display worktree usage guide |

Container Sandboxing (Podman)

AgentLoop supports optional container-based isolation using Podman, providing an additional layer of security for agent execution. When enabled, agents run inside containers with restricted filesystem and network access.

Note: Docker support is coming soon.

┌─────────────────────────────────────────────────────────┐
│                    Host System                          │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │              Podman Container                     │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │            Engineer Agent                   │  │  │
│  │  │                                             │  │  │
│  │  │  • Restricted filesystem access             │  │  │
│  │  │  • Network isolation (configurable)         │  │  │
│  │  │  • Resource limits (CPU, memory)            │  │  │
│  │  │  • No access to host system files           │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  │                       │                           │  │
│  │              Mount: /workspace                    │  │
│  │                       │                           │  │
│  └───────────────────────┼───────────────────────────┘  │
│                          │                              │
│                          ▼                              │
│              Project Directory (read/write)             │
└─────────────────────────────────────────────────────────┘

Why Use Sandboxing?

• Security - Agents cannot access sensitive files outside the project
• Isolation - Failed or misbehaving agents can't affect the host system
• Reproducibility - Consistent execution environment across different machines
• Resource Control - Limit CPU and memory usage per agent

Setup Commands

| Command | Description | |---------|-------------| | /setup podman | Interactive Podman installation and configuration | | /setup podman status | Check Podman installation and container status | | /setup podman help | Display sandboxing configuration guide | | /orchestrator sandbox | Manage sandbox settings for agent execution |

Background Daemon

The AgentLoop daemon allows you to run the orchestrator as a persistent background service. This is useful for long-running tasks, CI/CD integration, or when you want sessions to survive terminal closures.

┌──────────────────────────────────────────────────────────────────┐
│                         User Terminal                            │
│                                                                  │
│   $ agentloop                    $ agentloop                     │
│   > /daemon start                > /orchestrator status          │
│   Daemon started ✓               Connected to daemon...          │
│   > /exit                        Orchestrator: running           │
│   (terminal closed)              Tasks: 3 in-progress            │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Background Daemon Process                     │
│                                                                  │
│   ┌────────────────────────────────────────────────────────┐     │
│   │                   Orchestrator                         │     │
│   │                                                        │     │
│   │  • Continues running after terminal closes             │     │
│   │  • Processes tasks autonomously                        │     │
│   │  • Maintains session state and history                 │     │
│   │  • Reconnectable from any terminal                     │     │
│   │  • Automatic recovery from interruptions               │     │
│   └────────────────────────────────────────────────────────┘     │
│                                                                  │
│   Session Data: ~/.config/agentloop/daemon/                      │
│   Logs: ~/.config/agentloop/logs/                                │
└──────────────────────────────────────────────────────────────────┘

Use Cases

• Long-Running Tasks - Start a large refactoring job and disconnect; reconnect later to check progress
• CI/CD Integration - Run the daemon in your build pipeline for automated code generation
• Remote Development - SSH into a server, start the daemon, disconnect, and reconnect later. You can also work directly on mounted worktrees from your local IDE without needing to SSH
• Persistent Sessions - Conversation history and task state persist across CLI restarts

Daemon Commands

| Command | Description | |---------|-------------| | /daemon start | Start the background daemon service | | /daemon stop | Stop the running daemon | | /daemon restart | Restart the daemon (useful after configuration changes) | | /daemon status | Check if daemon is running and view connection info |

Interactive Commands

Core Commands

| Command | Description | |---------|-------------| | /help | Show all available commands | | /exit | Exit interactive mode | | /clear | Clear conversation history | | /init | Detect project type and initialize AgentLoop |

Orchestrator Commands

| Command | Description | |---------|-------------| | /orchestrator run | Run the orchestrator (processes tasks until complete) | | /orchestrator run --infinite | Run continuously, watching for new tasks | | /orchestrator generate <description> | Generate AGILE tasks from a project description | | /orchestrator status | Show current orchestrator status | | /orchestrator agents | Live agent monitoring with real-time status | | /orchestrator kanban | Open interactive kanban board | | /orchestrator stop | Stop the running orchestrator | | /orchestrator clear | Clear all tasks for the current project | | /orchestrator logs <task-id> | Show agent execution logs for a task |

DAG Commands

| Command | Description | |---------|-------------| | /orchestrator dag | Show DAG status with statistics | | /orchestrator dag ascii | ASCII visualization of task dependencies | | /orchestrator dag dot | Export DAG in DOT format |

Task Commands

| Command | Description | |---------|-------------| | /tasks | List all tasks in the current project | | /tasks --status <status> | Filter by status (todo, in-progress, review, done, blocked) | | /tasks --priority <priority> | Filter by priority (low, medium, high, critical) | | /task add <title> <description> | Add a new task |

Configuration Commands

| Command | Description | |---------|-------------| | /config show | Show current configuration | | /config set-token <token> | Set authentication token | | /config set-base-url <url> | Set API base URL | | /config clear | Clear configuration | | /settings show | Show current settings | | /settings telemetry [on\|off] | Enable or disable telemetry |

Jira Integration

| Command | Description | |---------|-------------| | /jira sync | Bidirectional sync with Jira | | /jira sync-dag | AI-powered sync with dependency analysis | | /jira configure siteUrl <url> | Set Jira site URL | | /jira configure projectKey <key> | Set Jira project key | | /jira configure boardId <id> | Set Jira board ID | | /jira set-auth <email> <token> | Set Basic Auth credentials | | /jira set-oauth <id> <secret> | Set OAuth credentials | | /jira authorize | Perform OAuth authorization | | /jira status | Show Jira integration status |

Mock & Testing

| Command | Description | |---------|-------------| | /mock | Open mock configuration view | | /mock status | Show mock configuration status | | /mock enable | Enable mock mode | | /mock disable | Disable mock mode |

Configuration

AgentLoop uses TOML configuration files with a layered priority system.

Configuration File Locations

| Location | Purpose | |----------|---------| | ./.agentloop/config.toml | Project-level config (local overrides) | | ~/.config/agentloop/config.toml | User-level config (global defaults) | | ~/.config/agentloop/ | Database, credentials, and cache |

Configuration Priority (Highest to Lowest)

1. Environment variables
2. Project config (./.agentloop/config.toml)
3. User config (~/.config/agentloop/config.toml)
4. Default values

Orchestrator Settings

[orchestrator]
max_parallel_agents = 1        # Number of agents that can run in parallel
use_worktrees = false          # Enable git worktrees for parallel development
worktrees_dir = ".worktrees"   # Directory for worktrees (relative to project)
cleanup_worktrees_on_complete = false  # Auto-cleanup worktrees after completion

| Option | Default | Env Variable | Description | |--------|---------|--------------|-------------| | max_parallel_agents | 1 | AGENTLOOP_MAX_PARALLEL_AGENTS | Maximum parallel agents | | use_worktrees | false | AGENTLOOP_USE_WORKTREES | Enable git worktrees | | worktrees_dir | .worktrees | AGENTLOOP_WORKTREES_DIR | Worktrees directory | | cleanup_worktrees_on_complete | false | AGENTLOOP_CLEANUP_WORKTREES | Auto-cleanup worktrees |

Container Sandbox Settings

[orchestrator.container_sandbox]
enabled = false                    # Enable Podman sandboxing
container_image = "agentloop-worker"
network_mode = "slirp4netns"       # none, slirp4netns, or host
memory_limit = "4g"
cpu_limit = "2"

[orchestrator.container_sandbox.agent_images]
engineer = "agentloop-worker"
qa-tester = "agentloop-qa-worker"
analyzer = "agentloop-worker"
product-manager = "agentloop-worker"

| Option | Default | Description | |--------|---------|-------------| | enabled | false | Enable container sandboxing | | container_image | agentloop-worker | Default container image | | network_mode | slirp4netns | Network isolation mode | | memory_limit | 4g | Memory limit per container | | cpu_limit | 2 | CPU limit per container |

GitHub Settings

[github]
enabled = true
token = "ghp_your_token_here"   # Or use GITHUB_PERSONAL_ACCESS_TOKEN env var

| Option | Default | Env Variable | Description | |--------|---------|--------------|-------------| | enabled | true | - | Enable GitHub integration | | token | - | GITHUB_PERSONAL_ACCESS_TOKEN | GitHub PAT (scopes: repo, workflow) |

Jira Settings

[jira]
siteUrl = "https://yourcompany.atlassian.net"
project = "PROJ"
boardId = "123"

# Basic Auth (simpler)
email = "[email protected]"
apiToken = "your_api_token"

# Or OAuth (more secure) - set via /jira set-oauth command
# clientId = "your_oauth_client_id"
# clientSecret = "your_oauth_client_secret"

| Option | Description | |--------|-------------| | siteUrl | Jira site URL | | project | Jira project key | | boardId | Board ID for accurate syncing (find in board URL) | | email | Email for Basic Auth | | apiToken | API token for Basic Auth |

Example Configuration

User-level defaults (~/.config/agentloop/config.toml):

[github]
enabled = true

[orchestrator]
max_parallel_agents = 4
use_worktrees = true

Project-level overrides (./.agentloop/config.toml):

[orchestrator]
max_parallel_agents = 10

[orchestrator.container_sandbox]
enabled = true
network_mode = "slirp4netns"

[jira]
siteUrl = "https://company.atlassian.net"
project = "MYPROJ"
boardId = "42"

Preview Features (Alpha)

The following features are in active development and available for early testing. They may change significantly or be incomplete.

Planning & Requirements

| Command | Description | |---------|-------------| | /planning | Start interactive PM agent planning session | | /questionnaire | Open questionnaire DAG view | | /bt | Open behavior tree debug view |

CLI Commands

# Start interactive session
agentloop

# Run orchestrator directly
agentloop orchestrator

# Single query mode
agentloop query "Your question here"

# Authentication management
agentloop auth status
agentloop auth logout
agentloop auth switch

# Configuration
agentloop config

Requirements

• Node.js >= 18.0.0
• npm or yarn
• Podman (optional, for container sandboxing)

License

See License

Support

For issues, questions, or contributions:

• Discord: Join our community
• Website: agentloop.run