![\"AgentLoop](\"https://www.agentloop.run/_next/image?url=%2Flogo_no_text_big.png&w=384&q=75&dpl=dpl_8iUBYWKRHdJzWcavR94X4nKpB4aC\")
\n \n\n \n \n \n
\n Autonomous Multi-Agent Orchestration for Software Development\n
\n\n\n Website •\n Installation •\n Features •\n Commands •\n Discord\n
\n\n---\n\n## Overview\n\nAgentLoop 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.\n\n## Installation\n\n### Global Installation (Recommended)\n\n```bash\nnpm install -g @trygentic/agentloop\n```\n\n### Local Installation\n\n```bash\nnpm install @trygentic/agentloop\n```\n\n### Run Without Installing\n\n```bash\nnpx @trygentic/agentloop\n```\n\n### Windows Users\n\nNative Windows is not currently supported. Please install AgentLoop using [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install):\n\n```bash\n# In WSL terminal\nnpm install -g @trygentic/agentloop\n```\n\n### Development Setup\n\n```bash\n# Clone with submodule\ngit clone --recursive https://github.com/trygentic/agentloop\n\n# Or if already cloned\ngit submodule update --init --recursive\n\n# Install and build\nnpm install\nnpm run build\n```\n\n## Quick Start\n\n```bash\n# Start interactive mode\nagentloop\n```\n\n### First-Time Setup\n\nOn first launch, AgentLoop opens the **Model Selection** screen. Choose how you want to connect:\n\n1. **AgentLoop Subscription** - Use subscription credits for premium models\n2. **Free Models** - Provided by OpenCode, no API key required\n3. **Bring Your Own API Key** - Connect your preferred provider:\n - **Anthropic** - Direct API key\n - **OpenAI** - Direct API key\n - **Google Gemini** - Direct API key\n - **OpenRouter** - Access 100+ models\n\nTo change models later, use the `/models` command.\n\n### Interacting with AgentLoop\n\nIn 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.\n\n```\n> Break down \"user authentication\" into tasks and add them to the board\n> What's the status of task 5? Mark it as in-progress\n> Have the engineer agent implement the login API endpoint\n> Ask the QA agent to test the new authentication flow\n> Add a dependency so task 3 must complete before task 7\n> Move all completed tasks to done and show me the kanban board\n```\n\nSlash 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.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ AgentLoop CLI │\n│ Interactive Mode / Query Mode / Daemon │\n└─────────────────────────────────┬───────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ ORCHESTRATOR │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ DAG Task Scheduler │ │\n│ │ Manages dependencies, parallelism, and execution order │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n│ ┌─────────────────────────────────────────────────────────────────────┐ │\n│ │ Behavior Tree Engine │ │\n│ │ Decision logic, validation layers, AI management │ │\n│ └─────────────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────┬───────────────────────────────────────────┘\n │\n ┌─────────────────────┼─────────────────────┐\n │ │ │\n ▼ ▼ ▼\n┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐\n│ Product Manager │ │ Engineer(s) │ │ QA Tester │\n│ Agent │ │ Agents │ │ Agent │\n│ │ │ │ │ │\n│ • Task breakdown │ │ • Code changes │ │ • Test execution │\n│ • AGILE planning │ │ • Git operations │ │ • Validation │\n│ • User stories │ │ • PR creation │ │ • Issue reporting │\n└───────────────────┘ └───────────────────┘ └───────────────────┘\n │ │ │\n │ ┌───────────┴───────────┐ │\n │ ▼ ▼ │\n │ ┌─────────────┐ ┌─────────────┐ │\n │ │ Worktree 1 │ │ Worktree 2 │ │\n │ │ (branch-a) │ │ (branch-b) │ │\n │ └─────────────┘ └─────────────┘ │\n │ │\n └──────────────────┬───────────────────────┘\n ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ Kanban Board │\n│ ┌─────────┐ ┌─────────────┐ ┌────────┐ ┌──────┐ ┌─────────┐ │\n│ │ Todo │ │ In Progress │ │ Review │ │ Done │ │ Blocked │ │\n│ │ │ │ │ │ │ │ │ │ │ │\n│ │ Task 1 │ │ Task 3 │ │ Task 5 │ │Task 7│ │ Task 9 │ │\n│ │ Task 2 │ │ Task 4 │ │ Task 6 │ │Task 8│ │ │ │\n│ └─────────┘ └─────────────┘ └────────┘ └──────┘ └─────────┘ │\n└─────────────────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│ External Integrations │\n│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │\n│ │ Jira │ │ GitHub │ │ MCP │ │\n│ │ Sync │ │ PRs │ │ Servers │ │\n│ └──────────┘ └──────────┘ └──────────┘ │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### How It Works\n\n1. **Task Creation** - Define tasks manually, generate them from descriptions using the Product Manager agent, or sync from Jira\n2. **DAG Scheduling** - The orchestrator analyzes task dependencies and creates an optimal execution plan\n3. **Parallel Execution** - Multiple engineer agents work simultaneously on independent tasks\n4. **Isolated Environments** - Each agent can work in its own git worktree or container sandbox\n5. **Quality Gates** - QA agents validate completed work before marking tasks done\n6. **Continuous Loop** - The orchestrator monitors progress and handles failures with self-healing recovery\n\n## Features\n\n### Multi-Agent Orchestration\n\nAgentLoop coordinates multiple specialized AI agents that work together seamlessly:\n\n- **Orchestrator Agent** - Manages overall workflow, delegates tasks, and ensures smooth handoffs between agents\n- **Product Manager Agent** - Breaks down project descriptions into AGILE tasks, user stories, and sprint plans\n- **Engineer Agent** - Autonomous code implementation with proper git workflows\n- **QA Tester Agent** - Automated testing, issue identification, and validation\n- **Code Analyzer Agent** - Deep codebase analysis for architecture and dependency understanding\n\n### Parallel Agent Execution\n\nMultiple engineer agents can work on different tasks simultaneously, dramatically reducing development time through true concurrency with configurable parallelism limits.\n\n### DAG-Based Task Management\n\nDefine 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.\n\n### Interactive Kanban Board\n\nVisual 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.\n\n### Intelligent Planning\n\nInteractive planning sessions help gather requirements, clarify scope, and generate comprehensive task breakdowns. The questionnaire system adapts based on previous answers for intelligent requirements gathering.\n\n### Self-Healing & Recovery\n\n- Automatic detection and recovery from orphaned tasks\n- Process health monitoring with cleanup of stale executions\n- Race condition prevention for task state consistency\n- Recovery from crashes and restarts\n\n### Behavior Tree System\n\nConfigurable, modular decision-making logic for agents using industry-standard behavior tree patterns. Includes validation layers and live AI management for adaptive agent behavior.\n\n### Jira Integration\n\nBidirectional synchronization with Jira Cloud:\n- OAuth 2.0 and Basic Auth support\n- Automatic task syncing\n- AI-powered DAG planning from Jira issues\n- Sprint and board management\n\n### Plugin System\n\nExtend AgentLoop with custom agents, behavior trees, and configurations:\n- Custom agent templates using markdown\n- Three-layer configuration (build-time, runtime, per-project)\n- MCP (Model Context Protocol) integration for external tools\n\n---\n\n## Git Worktrees\n\nAgentLoop 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.\n\n```\nMain Repository (.git)\n │\n ├── Main Working Directory (main branch)\n │\n ├── .worktrees/\n │ ├── feature-auth/ ← Agent 1 working here\n │ │ └── (branch: feature/auth)\n │ │\n │ ├── feature-api/ ← Agent 2 working here\n │ │ └── (branch: feature/api)\n │ │\n │ └── bugfix-login/ ← Agent 3 working here\n │ └── (branch: bugfix/login)\n```\n\n### Benefits\n\n- **No Merge Conflicts During Work** - Each agent has its own isolated working directory\n- **True Parallelism** - Multiple agents can compile, test, and modify code simultaneously\n- **Branch Isolation** - Changes in one worktree don't affect others until merged\n- **Efficient Storage** - Worktrees share the same Git objects, minimizing disk usage\n\n### Worktree Commands\n\n| Command | Description |\n|---------|-------------|\n| `/worktrees` | Open interactive worktree management view |\n| `/worktrees list` | List all active worktrees |\n| `/worktrees status` | Show worktree status summary |\n| `/worktrees help` | Display worktree usage guide |\n\n---\n\n## Container Sandboxing (Podman)\n\nAgentLoop 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.\n\n> **Note:** Docker support is coming soon.\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Host System │\n│ │\n│ ┌───────────────────────────────────────────────────┐ │\n│ │ Podman Container │ │\n│ │ ┌─────────────────────────────────────────────┐ │ │\n│ │ │ Engineer Agent │ │ │\n│ │ │ │ │ │\n│ │ │ • Restricted filesystem access │ │ │\n│ │ │ • Network isolation (configurable) │ │ │\n│ │ │ • Resource limits (CPU, memory) │ │ │\n│ │ │ • No access to host system files │ │ │\n│ │ └─────────────────────────────────────────────┘ │ │\n│ │ │ │ │\n│ │ Mount: /workspace │ │\n│ │ │ │ │\n│ └───────────────────────┼───────────────────────────┘ │\n│ │ │\n│ ▼ │\n│ Project Directory (read/write) │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Why Use Sandboxing?\n\n- **Security** - Agents cannot access sensitive files outside the project\n- **Isolation** - Failed or misbehaving agents can't affect the host system\n- **Reproducibility** - Consistent execution environment across different machines\n- **Resource Control** - Limit CPU and memory usage per agent\n\n### Setup Commands\n\n| Command | Description |\n|---------|-------------|\n| `/setup podman` | Interactive Podman installation and configuration |\n| `/setup podman status` | Check Podman installation and container status |\n| `/setup podman help` | Display sandboxing configuration guide |\n| `/orchestrator sandbox` | Manage sandbox settings for agent execution |\n\n---\n\n## Background Daemon\n\nThe 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.\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ User Terminal │\n│ │\n│ $ agentloop $ agentloop │\n│ > /daemon start > /orchestrator status │\n│ Daemon started ✓ Connected to daemon... │\n│ > /exit Orchestrator: running │\n│ (terminal closed) Tasks: 3 in-progress │\n│ │\n└──────────────────────────────────────────────────────────────────┘\n │\n ▼\n┌──────────────────────────────────────────────────────────────────┐\n│ Background Daemon Process │\n│ │\n│ ┌────────────────────────────────────────────────────────┐ │\n│ │ Orchestrator │ │\n│ │ │ │\n│ │ • Continues running after terminal closes │ │\n│ │ • Processes tasks autonomously │ │\n│ │ • Maintains session state and history │ │\n│ │ • Reconnectable from any terminal │ │\n│ │ • Automatic recovery from interruptions │ │\n│ └────────────────────────────────────────────────────────┘ │\n│ │\n│ Session Data: ~/.config/agentloop/daemon/ │\n│ Logs: ~/.config/agentloop/logs/ │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### Use Cases\n\n- **Long-Running Tasks** - Start a large refactoring job and disconnect; reconnect later to check progress\n- **CI/CD Integration** - Run the daemon in your build pipeline for automated code generation\n- **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\n- **Persistent Sessions** - Conversation history and task state persist across CLI restarts\n\n### Daemon Commands\n\n| Command | Description |\n|---------|-------------|\n| `/daemon start` | Start the background daemon service |\n| `/daemon stop` | Stop the running daemon |\n| `/daemon restart` | Restart the daemon (useful after configuration changes) |\n| `/daemon status` | Check if daemon is running and view connection info |\n\n---\n\n## Interactive Commands\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `/help` | Show all available commands |\n| `/exit` | Exit interactive mode |\n| `/clear` | Clear conversation history |\n| `/init` | Detect project type and initialize AgentLoop |\n\n### Orchestrator Commands\n\n| Command | Description |\n|---------|-------------|\n| `/orchestrator run` | Run the orchestrator (processes tasks until complete) |\n| `/orchestrator run --infinite` | Run continuously, watching for new tasks |\n| `/orchestrator generate