Concepts

planeai orchestrates multiple AI coding agents in parallel. Before diving into configuration and workflows, it helps to understand how the core pieces fit together: projects contain tasks, sessions run providers on a backend, and auto-dispatch ties it all together by assigning tasks to sessions automatically.

Sessions

A session is a persistent terminal running an AI agent. Each session has its own shell, its own working directory, and (optionally) its own git branch or worktree. You can have as many sessions running in parallel as your machine can handle.

Sessions have a lifecycle: they start when you create them (or when auto-dispatch launches one), they run while the agent is working, and they can be archived or deleted when the work is done. If the agent process exits, the session enters an “exited” state but remains visible so you can restart it or inspect its output.

Sessions can be linked to a task. When a session is linked, planeai tracks which task it’s working on, and the sidebar shows agent status (busy, idle, needs review) next to the task.

Providers

A provider is the configuration layer between planeai and an AI agent CLI. It tells planeai how to start a session, how to start it on a task prompt, and what flags to use in autonomous mode.

planeai ships with no hardcoded agent — it works with any CLI that accepts text input. You configure providers for the agents you use (Kiro, Claude, Copilot, Codex, or anything else). Each provider defines:

• command — how to start a new agent session
• prompt_command - the arguments that start the agent on a task prompt
• yolo_flag — what flag enables autonomous mode (skipping confirmations)
• autonomous_prompt_template — how task details are formatted when dispatched

You can have multiple providers configured and choose which one to use per session or per dispatch rule.

Session Backends

The backend controls how planeai manages terminal processes behind the scenes. There are three options:

Local (default) — runs the agent as an in-process PTY. Lightweight, no dependencies, but sessions terminate when you close the app. Best for most users who keep the app open while working.

tmux — delegates session management to tmux. Sessions survive app restarts because tmux keeps them alive in the background. Requires tmux installed on your system. Not available on Windows.

Daemon (experimental) — a built-in background process that persists sessions across app restarts without requiring tmux. Still under active development and may have stability issues.

Choose based on whether you need sessions to survive app closures. If you do, use tmux (stable) or daemon (experimental). If not, local is simpler.

Projects

A project is a registered directory on your filesystem — typically a git repository. Registering a project tells planeai where your code lives so it can create sessions, worktrees, and tasks scoped to that codebase.

By default the sidebar organizes everything by project: tasks appear under the project they belong to, and sessions are grouped by their associated project. You can have multiple projects registered simultaneously. You can also group the sidebar by task status to see the work of every project in one list.

If you move or rename a project’s folder outside planeai, the sidebar flags the project with a warning icon. Click the icon, choose Locate folder… from the project’s menu or from the New Task and New Session forms, then pick the folder’s new location. planeai checks that it is a git repository and reattaches the project’s worktree sessions to it. Tasks and sessions are kept, but agent conversations started in the old folder may not resume. Until the folder is located, planeai does not start new sessions for that project.

Tasks

Tasks are planeai’s built-in work tracker. Each task represents a unit of work — a bug to fix, a feature to build, a refactor to perform. Tasks live inside a project and have:

• Key — auto-assigned identifier (e.g., PLA-1, PLA-2)
• Title — short, actionable description
• Description — detailed context for the agent that will work on it
• Status — todo, in_progress, in_review, or done
• Priority — numeric priority (higher = more important for dispatch)
• Blocked by — other task keys that must complete before this one is eligible
• Parent — optional parent task for subtask hierarchies
• Base branch — which git branch to start from when creating a worktree

Tasks appear in the sidebar grouped by status, either inside each project or across all projects. Clicking a task either jumps to its linked session (if one exists) or starts a new session for it. You can create tasks from the GUI, the CLI, or directly from an agent session using the built-in agent skills.

The bundled Jira plugin manages Jira Cloud OAuth and manual configured-source synchronization. Synced issues are imported as PlaneAI tasks, appear in the sidebar, and can be assigned to a PlaneAI project as child tasks. Writeback and periodic synchronization remain deferred. See the Task Management guide for the current scope.

Auto-Dispatch (Symphony Mode)

Auto-dispatch is planeai’s orchestrator. When enabled, it continuously polls your task board, picks the highest-priority ready task, and dispatches it to an available session slot — fully autonomously.

The loop is simple: poll → dispatch → reconcile → notify. Tasks with unmet blockers are skipped. When a session completes its work, planeai moves the task to done and frees the slot for the next one. Lifecycle hooks fire at each transition, letting you automate commits, notifications, or any shell command.

Auto-dispatch turns planeai from a multi-terminal manager into a task orchestration system. You feed it tasks, it feeds agents work. See the Auto-Dispatch guide for configuration details.

Git Worktrees

When you run multiple agents in parallel on the same repository, they’ll conflict if they share a working directory. planeai solves this with git worktrees — each session gets its own checkout of the repository on its own branch.

Worktrees are created automatically when you start a session with a task (or when auto-dispatch launches one). Each agent works in complete isolation: no merge conflicts, no stash juggling, no stepping on each other’s changes. When the work is done, you merge the branch like any other feature branch.

This is what makes true parallel development possible — three agents can work on three different features simultaneously without interference.

You can also start a session on a branch that already exists. Git lets a branch live in only one checkout at a time, so when another worktree (or the main checkout) already has that branch, the new session runs there instead. planeai shows a warning naming that checkout, and any session already running in it, because the sessions then share one working directory.