agentplan Quickstart — install, create projects, and integrate with AI tools

1) Installation

Install agentplan from PyPI and verify the CLI is available.

python3 -m pip install --upgrade agentplan

# macOS (Homebrew Python):
pipx install agentplan

agentplan --help

2) Your first project

Let's say you're building a new API feature. You need research, implementation, and tests — perfect for splitting across agents.

# initialize agentplan in your repo
agentplan init

# create a project and add tickets with dependencies
agentplan create "api-feature" --dir .
agentplan ticket add api-feature "Research caching strategies" --priority high --tag research
agentplan ticket add api-feature "Implement API endpoints" --priority high --tag backend
agentplan ticket add api-feature "Write integration tests" --priority medium --tag testing

# wire dependencies — implementation waits for research, tests wait for implementation
agentplan depend api-feature 2 --on 1
agentplan depend api-feature 3 --on 2

3) Assign work to agents

Agents claim tickets automatically based on priority and dependency order. As each ticket completes, the next one unblocks.

# see which ticket is ready
agentplan next api-feature          # → #1 Research caching strategies

# claim it for an agent with a timeout
agentplan claim api-feature --agent claude --timeout 30

# ... agent works on the ticket ...

# mark complete — #2 auto-unblocks
agentplan ticket done api-feature 1 --agent claude
agentplan next api-feature          # → #2 Implement API endpoints (now unblocked!)

4) Monitor progress

Check project status from the CLI or launch the visual dashboard.

# CLI status overview
agentplan status api-feature

# launch the real-time dashboard
agentplan dashboard --open

5) Integration examples

Connect agentplan to your AI tools. Each snippet shows how to pull the next ticket and hand it to an agent.

Claude Code / Claude (Anthropic)

# get next ticket from agentplan, then hand to Claude Code
NEXT_TICKET=$(agentplan next marketing-site --format compact)
claude "Work on this ticket from agentplan:\n\n$NEXT_TICKET\n\nWhen complete, summarize what changed and any follow-ups."

Codex (OpenAI)

# fetch next task and execute with Codex in your project directory
TASK=$(agentplan next marketing-site --format compact)
codex exec --full-auto "Implement this agentplan ticket:\n\n$TASK\n\nRun tests and report results."

OpenClaw workflow

# example: assign a ticket to a named OpenClaw worker before execution
agentplan ticket start marketing-site 2 --agent dash

# your OpenClaw prompt can include:
# "Run: agentplan next marketing-site --format compact
# Then implement that ticket and mark it done with:
# agentplan ticket done marketing-site <id> --agent dash"

Generic Python integration

import subprocess

def run(cmd: list[str]) -> str:
    return subprocess.check_output(cmd, text=True).strip()

project = "marketing-site"
next_ticket = run(["agentplan", "next", project, "--format", "compact"])

prompt = f"""Implement this ticket:\n\n{next_ticket}\n\nReturn changed files and test results."""

# Replace with your model/client call:
print("Send to your model:")
print(prompt)

# After successful implementation, mark done (replace '1' with actual ticket id)
# run(["agentplan", "ticket", "done", project, "1", "--agent", "python-worker"])

6) CLI reference (key commands)

Core commands you'll use daily.

agentplan init

Initialize agentplan metadata in the current repository.

agentplan create <project-name>

Create a new tracked project.

agentplan ticket add <project> "<title>" [--priority] [--tag]

Add a ticket to a project.

agentplan next <project>

Show the next actionable ticket based on priority/dependencies.

agentplan ticket start <project> <ticket-id> --agent <name>

Assign ownership to a worker or person.

agentplan ticket done <project> <ticket-id> --agent <name>

Mark a ticket complete with explicit executor attribution.

agentplan status <project>

Display project progress and open work.

agentplan list

List all tracked projects.

7) Dashboard

Launch the built-in web dashboard for real-time project visibility. Requires Flask.

# install with dashboard extras
pip install "agentplan[dashboard]"

# launch and open in browser
agentplan dashboard --open

# custom port
agentplan dashboard --port 8080 --open

# stop the dashboard
agentplan dashboard --stop

Dashboard Overview

Project cards with SVG progress rings showing completion at a glance.

Kanban Board

Tickets organized by status with priority stripes and tag pills.

Ticket Detail

Slide-over panel with subtasks, dependencies, and audit timeline.

Live Activity Feed

Real-time stream of ticket activity via Server-Sent Events (SSE).