Metadata-Version: 2.4
Name: agentplan
Version: 0.8.6
Summary: A shared to-do list for AI agents. Dependency-aware task queue, zero dependencies, pure Python.
Author-email: Dushyant Garg <dushyantgarg3@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://fraction12.github.io/agentplan/
Project-URL: Repository, https://github.com/fraction12/agentplan
Project-URL: Documentation, https://fraction12.github.io/agentplan/quickstart.html
Project-URL: Bug Tracker, https://github.com/fraction12/agentplan/issues
Project-URL: Changelog, https://github.com/fraction12/agentplan/blob/main/CHANGELOG.md
Keywords: ai-agent,agent,multi-agent,task-queue,project-management,cli,automation,orchestration,ticket-tracking,dependency-graph,llm,claude,codex,openai,anthropic,ai-coordination,agent-framework,sqlite,zero-dependencies
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: dashboard
Requires-Dist: flask>=3.0; extra == "dashboard"
Dynamic: license-file

agentplan
  
Asana for AI agents — a task board that any AI tool can drive.

  Python versions

agentplan is **Asana for AI agents** — a shared task board that AI tools can use as the source of truth for work.

- Persistent project + ticket queue
- Dependency tracking with automatic unblocking
- Atomic ticket claiming (safe for concurrent agents)
- Web dashboard for visibility
- Local-first SQLite storage
- Built-in plugins for Claude Code and Codex

## What AgentPlan Is

AgentPlan is the coordination layer for AI work.

Use it to:
- create a project for a repo
- break work into small tickets
- track dependencies and progress
- let agents claim the next unblocked task
- watch the work move in the dashboard

AgentPlan is not the main execution engine. Claude Code, Codex, and other tools do the planning and implementation work. AgentPlan keeps the shared backlog, ticket state, and history in one place.

## Start in 3 steps

```bash
# 1) Install
pip install agentplan

# On macOS (Homebrew Python):
pipx install agentplan

# 2) Connect your AI tool
agentplan setup claude    # Claude Code
agentplan setup codex     # Codex CLI

# 3) Tell your AI to plan
# In Claude Code: /agentplan:plan
# Or just say: "plan a new project for this repo"
```

## Typical workflow

1. Open Claude Code, Codex, or another supported AI tool.
2. Ask it to create an AgentPlan project for the current repo.
3. Let it break the work into tickets with dependencies.
4. Have the AI tool work ticket-by-ticket using `agentplan next` and `agentplan claim`.
5. Use the dashboard to monitor progress and inspect ticket state.

Short version: plan in the AI tool, track in AgentPlan, execute through the AI tool's own loop or scheduled workflow.

## Quickstart

```bash
# Create a project linked to the current repo
agentplan create "Ship v1" --dir .

# Add a few tickets
agentplan ticket add ship-v1 "Set up database" --priority high
agentplan ticket add ship-v1 "Implement API" --priority high
agentplan ticket add ship-v1 "Write tests" --priority medium

# Add dependencies where needed
agentplan depend ship-v1 2 --on 1
agentplan depend ship-v1 3 --on 2

# See what's ready to work on
agentplan next ship-v1

# Claim the next unblocked ticket
agentplan claim ship-v1

# Mark it done
agentplan ticket done ship-v1 1

# Check progress
agentplan status ship-v1
```

## AI tool setup

The `setup` command installs plugins from the pip package, so the AI tool can understand the AgentPlan workflow without cloning anything extra:

```bash
# Claude Code — registers as a local marketplace plugin
agentplan setup claude

# Codex CLI — copies the skill into ~/.codex/skills/
agentplan setup codex
```

After setup, restart the AI tool.

### Claude Code flow

- `/agentplan:plan` creates a project and tickets from the conversation
- `/agentplan:status` shows project progress
- `/agentplan:loop` generates the prompt/instructions for Claude's own loop or cron-driven workflow

### Codex flow

- use the installed `agentplan` skill
- create a project, add tickets, and work from `agentplan next` / `agentplan claim`
- keep AgentPlan as the shared backlog if Claude and Codex are both working on the same repo

## Core CLI commands

### Project lifecycle

| Command | Description |
|---------|-------------|
| `agentplan create` | Create a project (with optional `--ticket` flags) |
| `agentplan list` | List all projects |
| `agentplan status <project>` | Show project progress and ticket states |
| `agentplan close <project>` | Close a completed project |
| `agentplan archive <project>` | Archive a project |
| `agentplan remove <project>` | Permanently remove a project |

### Ticket workflow

| Command | Description |
|---------|-------------|
| `agentplan ticket add <project> "title"` | Add a ticket |
| `agentplan ticket list <project>` | List tickets |
| `agentplan ticket done <project> <num>` | Mark ticket done |
| `agentplan ticket skip <project> <num>` | Skip a ticket |
| `agentplan ticket block <project> <num>` | Block a ticket |
| `agentplan ticket fail <project> <num>` | Mark ticket failed |
| `agentplan ticket edit <project> <num>` | Edit ticket details |
| `agentplan next <project>` | Show next unblocked tickets |
| `agentplan claim <project>` | Atomically claim the next unblocked ticket |
| `agentplan search <query>` | Search tickets across all projects |

### Dependencies, logs, and notes

| Command | Description |
|---------|-------------|
| `agentplan depend <project> <ticket> --on <dep>` | Add dependency |
| `agentplan undepend <project> <ticket> --on <dep>` | Remove dependency |
| `agentplan log <project>` | Add a log entry |
| `agentplan note <project>` | Set a note on project or ticket |
| `agentplan attach <project>` | Attach a file or URL |
| `agentplan history <project> <ticket>` | Show ticket state transitions |

### Utilities

| Command | Description |
|---------|-------------|
| `agentplan setup [claude\|codex]` | Install AI tool plugin |
| `agentplan dashboard` | Launch web dashboard |
| `agentplan completion` | Print shell completion script |

## Dashboard

```bash
# install with dashboard extras (requires Flask)
pip install "agentplan[dashboard]"

agentplan dashboard
# or run in background:
agentplan dashboard --background
```

Open `http://127.0.0.1:5001` to view projects, ticket board, and activity. Create and edit tickets directly from the UI.

## Advanced workflows

AgentPlan also includes advanced and power-user surfaces for orchestration, CI, and other automation-heavy workflows. Those are intentionally de-emphasized in the main UX.

If you are evaluating AgentPlan for the first time, start with:
- project creation
- tickets and dependencies
- `next` and `claim`
- dashboard visibility
- Claude/Codex plugin flow

## Security + docs

- Security policy: `docs/security/security.md`
- Privacy: `docs/security/privacy.md`
- Canonical docs alignment baseline: `docs/docs-alignment-canonical-story.md`

## License

MIT
