agentplan 0.3.2

Multi-agent task queue and project planner CLI

agentplan

A shared to-do list for AI agents.

Quickstart · The Agent Loop · Commands · Why agentplan? · Community

Agent Loop Demo (Terminal Recording Preview)

$ agentplan create "Launch docs portal" \
    --ticket "Initialize repo + CI" \
    --ticket "Build docs site shell" \
    --ticket "Write auth middleware" \
    --ticket "Add onboarding guide"
✓ Created project: launch-docs-portal

# agent-a (builder) claims the next highest-priority unblocked ticket
$ agentplan next launch-docs-portal --format compact
📋 launch-docs-portal: 0/4 done | Next: [1] Initialize repo + CI

$ agentplan ticket start launch-docs-portal 1 --agent agent-a
▶ Ticket #1 started (by agent-a)

$ codex exec --full-auto "Initialize repo + CI"
... creates repo scaffolding, CI workflow, pyproject ...

$ agentplan ticket done launch-docs-portal 1 --agent agent-a
✓ Ticket #1 marked done (by agent-a)

# agent-b (reviewer) checks status and discovers follow-up work
$ agentplan status launch-docs-portal
1/4 done, 0 blocked, next: [2] Build docs site shell
  ✓ 1. Initialize repo + CI
  ☐ 2. Build docs site shell
  ☐ 3. Write auth middleware
  ☐ 4. Add onboarding guide

$ agentplan ticket add launch-docs-portal \
    "Harden CI cache keys to avoid stale lockfile reuse"
✓ Added ticket #5

$ agentplan depend launch-docs-portal 5 --on 1
✓ Added dependency: #5 depends on #1

# agent-c (security) takes the newly discovered work
$ agentplan next launch-docs-portal --tag security --format compact
📋 launch-docs-portal: 1/5 done | Next: [5] Harden CI cache keys to avoid stale lockfile reuse

$ agentplan ticket start launch-docs-portal 5 --agent agent-c
▶ Ticket #5 started (by agent-c)

$ codex exec --full-auto "Harden CI cache keys to avoid stale lockfile reuse"
... updates workflow cache key + lockfile checks ...

$ agentplan ticket done launch-docs-portal 5 --agent agent-c
✓ Ticket #5 marked done (by agent-c)

# loop continues until queue drains
$ agentplan next launch-docs-portal --format compact
📋 launch-docs-portal: 2/5 done | Next: [2] Build docs site shell

---

Multiple AI agents. One shared work queue. Zero infrastructure.

agentplan is a CLI that gives your agents a persistent task queue with dependency resolution. Any agent that can run shell commands can use it — Claude Code, Codex, GPT, Cursor, Windsurf, OpenClaw, or your own.

No SDK. No framework. No Python dependencies beyond stdlib. Just three commands:

agentplan next myproject           # What should I work on?
agentplan ticket done myproject 3  # Done with ticket 3
agentplan ticket add myproject "new thing I found"  # Add work

That's the entire integration.

Quickstart

pip install agentplan

# Create a project with tickets
agentplan create "Build my app" \
  --ticket "Set up database schema" \
  --ticket "Build API endpoints" \
  --ticket "Write tests" \
  --ticket "Deploy to production"

# Add dependencies — tests need API, deploy needs everything
agentplan depend build-my-app 3 --on 2
agentplan depend build-my-app 4 --on 1,2,3

# Ask what's next
agentplan next build-my-app
# → [1] Set up database schema

The Agent Loop

The real power of agentplan is what happens when you connect it to autonomous agents. Here's the pattern:

┌─────────────────────────────────────────────┐
│  Agent A (cron, every 15 min)               │
│  1. agentplan next myproject                │
│  2. Do the work                             │
│  3. agentplan ticket done myproject <id>    │
└─────────────────────────────────────────────┘
         ↕ shared queue
┌─────────────────────────────────────────────┐
│  Agent B (cron, offset by 8 min)            │
│  1. agentplan status myproject              │
│  2. Review what Agent A did                 │
│  3. agentplan ticket add myproject "..."    │
└─────────────────────────────────────────────┘

Agent A pulls the next unblocked ticket, does the work, marks it done. Agent B reviews the work, spots issues, adds new tickets. The queue is self-sustaining — no coordinator, no orchestrator, no message passing. Just a shared pile of work.

Real-world example: OpenClaw + Codex

This is how we actually use it — an OpenClaw agent coordinating with OpenAI Codex:

# Cron job fires every 15 minutes
NEXT=$(agentplan next my-redesign --format compact)

if [ -z "$NEXT" ]; then
  echo "All done — killing crons"
  exit 0
fi

# Spawn Codex to do the work
codex exec --full-auto "$NEXT"

# Mark done
agentplan ticket done my-redesign "$TICKET_ID"

A second cron (running a cheaper model) reviews and adds tickets:

# Review cron — offset by 8 minutes
agentplan status my-redesign
# ... inspect recent changes ...
agentplan ticket add my-redesign "Fix: button hover state missing"

Two agents, zero coordination code, self-healing work queue.

Why agentplan?

	agentplan	CrewAI	AutoGen	LangGraph
Install	pip install agentplan	pip install crewai	pip install autogen-agentchat	pip install langgraph
Infrastructure	None. Single SQLite file.	Python runtime + config	Python runtime + async	Python runtime + graph def
Works with	Any agent with a terminal	CrewAI agents only	AutoGen agents only	LangGraph nodes only
Integration	3 shell commands	Python SDK	Python SDK	Python SDK
Dependencies	Zero (stdlib only)	30+ packages	20+ packages	15+ packages
What it is	Shared task queue	Agent framework	Agent framework	Orchestration framework

agentplan is not a framework. It doesn't run your agents, define their roles, or manage their conversations. It gives agents that already exist a way to coordinate through work.

You already have agents. agentplan gives them a shared to-do list.

Features

• Dependency resolution — next returns only unblocked tickets. No manual sequencing.
• Circular dependency detection — prevents invalid dependency graphs before they happen.
• Auto-completion — projects close automatically when all tickets are done or skipped.
• Multiple output formats — full, compact (~50 tokens, ideal for agent prompts), and json.
• Progress logging — timestamped entries for cross-session continuity.
• Attachments — link files, URLs, or references to any project or ticket.
• Zero dependencies — Python stdlib only. Single file. No virtual environment needed.
• SQLite storage — fast, reliable, single-file persistence at ~/.agentplan/agentplan.db.

Commands

agentplan create <title> [--ticket "..."]   # Create project with tickets
agentplan ticket add <project> <title>      # Add a ticket
agentplan ticket done <project> <id...>     # Mark ticket(s) done (supports 1 2 3 or 1,2,3)
agentplan ticket skip <project> <id...>     # Skip ticket(s)
agentplan ticket start <project> <id>       # Mark in-progress
agentplan ticket list <project>             # List all tickets
agentplan next [project]                    # Next unblocked ticket
agentplan status [project]                  # Project status
agentplan depend <project> <id> --on <ids>  # Add dependencies
agentplan log <project> <entry>             # Log progress
agentplan attach <project> <label> <loc>    # Attach file/URL
agentplan close <project> [--abandon]       # Close project
agentplan list [--status ...]               # List all projects
agentplan remove <project> [--ticket <id>]  # Remove project/ticket
agentplan version                           # Show version

Output Formats

Full (default):

My Project [active] — 2/4 done
  ✓ 1. Setup
  ✓ 2. Build
  ▶ 3. Test (in-progress)
  ⏳ 4. Deploy (blocked — waiting on 3)

Compact (~50 tokens, optimized for agent context windows):

📋 My Project: 2/4 done | Next: [3] Test ▶

JSON (for programmatic use):

{"id": 1, "slug": "my-project", "title": "My Project", "status": "active", "done": 2, "total": 4}

Configuration

Variable	Default	Description
AGENTPLAN_DIR	~/.agentplan	Database directory
AGENTPLAN_DB	~/.agentplan/agentplan.db	Database file path

Compatible Platforms

agentplan works with any agent or tool that can execute shell commands:

• OpenClaw — Multi-agent orchestration via cron jobs
• Claude Code — Anthropic's CLI agent
• OpenAI Codex — OpenAI's coding agent
• Cursor / Windsurf — AI-powered editors
• Cron jobs — Scheduled autonomous work loops
• CI/CD pipelines — GitHub Actions, Jenkins, etc.
• Any terminal — If it can run agentplan next, it can coordinate

License

MIT — Dushyant Garg, 2026