AIPM — The AI Project Manager

Manage large projects distributed over multiple issue trackers and tools — from a single local workspace.

aipm summary day:

aipm ticket list:

AIPM syncs issues from Jira and GitHub into a local git-tracked directory of Markdown files. It then uses GitHub Copilot (with graceful fallback) to summarize changes, update project plans, and generate reports — all from the command line.

New here? Start with the Tutorial — it walks you through setup, tickets, horizons, and daily workflow.
For the planning concept in depth, see Planning & Time Horizons.
Learn how automated ticket checking works in Check.
See how AI-powered project reports work in Summary.
Troubleshoot Copilot issues with Debugging.
Extend AIPM with custom Skills.
Learn about the Ticket Format and directory structure.

---

Features

• Multi-source sync — pull issues from Jira and GitHub into one unified tickets/ directory
• Markdown-first — every ticket, milestone, and goal is a plain Markdown file, version-controlled with git
• AI-powered insights — diff summaries, plan updates, and project reports powered by the GitHub Copilot SDK
• Works offline — all AI features fall back to structured local analysis when Copilot is unavailable
• Simple CLI — seven commands cover the full project management lifecycle

Installation

Requires Python 3.14+ and uv.

Local (development)

uv sync
uv run aipm <command>

Global (available everywhere)

Install aipm so it's available in any terminal session:

just install
# or manually:
uv tool install -e .

If ~/.local/bin is not on your PATH, add it:

export PATH="$HOME/.local/bin:$PATH"

Then use aipm directly:

aipm <command>

To uninstall:

just uninstall

Copilot CLI (optional, recommended)

AIPM uses the GitHub Copilot CLI for AI-powered analysis. Without it, all features still work but fall back to keyword-based analysis.

The Python SDK (github-copilot-sdk) bundles its own Copilot CLI binary, so you don't need to install it separately. However, you must authenticate it before first use:

# 1. Launch the bundled Copilot CLI in interactive mode:
.venv/lib64/python3.14/site-packages/copilot/bin/copilot

# 2. Inside the Copilot shell, type:
/login

# 3. Follow the OAuth device flow to authenticate with your GitHub account.
# 4. Once authenticated, exit the shell (Ctrl+D or /exit).

Alternatively, you can set a GitHub token in your environment:

export GITHUB_TOKEN="your-token-here"

Manual Copilot CLI install (useful for debugging and testing):

# Linux / macOS:
just install-copilot
# or manually:
curl -fsSL https://gh.io/copilot-install | bash

# Via npm (any platform):
npm install -g @github/copilot

Quick Start

# 1. Initialize a new project
uv run aipm init

# 2. Connect your issue trackers
uv run aipm add jira https://mycompany.atlassian.net/browse/PROJ
uv run aipm add github https://github.com/owner/repo

# 3. Sync issues to local Markdown files
uv run aipm sync

# 4. Review what changed
uv run aipm diff

# 5. Update the project plan
uv run aipm plan

# 6. Get a summary
uv run aipm summary week

# 7. Commit everything
uv run aipm commit

Commands

🔴 🟡 🟢   ~/my-project ❯ aipm --help Usage: aipm [OPTIONS] COMMAND [ARGS]... AIPM - The AI Project Manager. Manage large projects distributed over multiple issue trackers and tools. Options: --version Show the version and exit. --help Show this message and exit. Commands: add Add an issue source to the project. commit Commit the updated tickets and plan. diff Summarize changes currently staged for commit. init Initialize a new AIPM project in the current directory. plan Update the project plan based on current ticket status. report Generate a full set of reports under generated/. summary Generate a high-level project summary. sync Sync issues from all configured sources to the tickets directory. ticket Manage local tickets. upgrade Upgrade existing tickets by filling in missing fields.

Command	Description
aipm init	Initialize a new project — creates tickets/, generated/, milestones.md, goals.md, README.md, and aipm.toml
aipm add jira <URL>	Add a Jira project as an issue source (with optional JQL filter)
aipm add github <URL>	Add a GitHub repository as an issue source
aipm sync	Fetch issues from all sources and write them as Markdown to tickets/<source>/
aipm diff	Summarize the currently staged git changes using AI (or structured fallback)
aipm plan	Update milestones.md based on current ticket horizons and statuses
aipm summary [day|week|month|year|all] [all|me|username]	Generate a project summary filtered by time horizon and user
aipm ticket add	Create a local ticket (interactive or via flags -t, -p, -a, -d, -l, --horizon, --due, --repo)
aipm ticket list	List all local tickets in a table
aipm ticket upgrade	Scan existing tickets and interactively fill in missing fields (horizon, priority, etc.)
aipm upgrade	Upgrade existing tickets by filling in missing fields interactively
aipm report	Generate all reports (summaries + project plan) under the configured output directory
aipm report -f md	Generate Markdown reports only
aipm report -f html	Generate HTML reports only
aipm check [TICKET_KEY]	Check ticket completion against configured repos using Copilot
aipm check --debug	Check with full Copilot prompt/response output
aipm commit	Stage AIPM files, generate a commit message, and commit

Demo reports: See a live example of generated reports at christianjann.github.io/aipm/report/index.html.

Time Horizons

AIPM uses time horizons instead of rigid priority levels to organize work. Every ticket carries a horizon that tells you when it should be tackled:

Horizon	Meaning
now	Drop everything — must be done today
week	Should be finished by end of this week
next-week	Needs to be done by end of next week
month	Sometime this or next month
year	Finish within the year; strategic
sometime	Nice-to-have; maybe later

# Create a ticket with a horizon
aipm ticket add -t "Fix login crash" --horizon now -p high

# Link a ticket to a repo for checking
aipm ticket add -t "Add CI pipeline" --horizon week --repo /path/to/project

# Check if tasks are done (most urgent first)
aipm check

# Check a specific ticket
aipm check L-000001

# Urgent items only
aipm summary day

# This week's workload
aipm summary week

# Full picture
aipm summary all

Tickets can also carry an optional --due YYYY-MM-DD date. If a due date is set without an explicit horizon, AIPM infers the horizon automatically.

See doc/planning.md for the full planning concept.

Project Structure

After you run aipm init, add tickets, and generate reports, your workspace will be organized as follows:

my-project/
├── aipm.toml          # Project configuration and source definitions
├── tickets/           # Synced issue tickets (one folder per issue)
│   ├── local/         # Local-only tickets
│   │   ├── 000001_setup_ci/
│   │   │   └── ISSUE.md
│   │   └── 000002_write_docs/
│   │       └── ISSUE.md
│   ├── MYPROJ/        # Jira source named "MYPROJ"
│   │   ├── MYPROJ-1_implement_feature/
│   │   │   └── ISSUE.md
│   │   └── MYPROJ-2_fix_bug/
│   │       └── ISSUE.md
│   └── myrepo/        # GitHub source named "myrepo"
│       ├── 42_add_readme/
│       │   └── ISSUE.md
│       └── 87_refactor_api/
│           └── ISSUE.md
├── milestones.md      # Project milestones grouped by horizon
├── goals.md           # Project goals
├── generated/         # Generated reports (summaries, plan) — configurable via `output_dir` in `aipm.toml`
│   ├── summary_day.md / .html
│   ├── summary_week.md / .html
│   ├── summary_week_alice.md / .html
│   ├── plan.md / .html
│   └── ...
└── README.md          # Project summary

Environment Variables

Variable	Required	Description
JIRA_TOKEN	For Jira sources	Jira API token or personal access token
JIRA_EMAIL	For Jira Cloud	Email address for Jira Cloud basic auth
GITHUB_TOKEN	For private repos	GitHub personal access token

Development

# Install with dev dependencies
uv sync

# Run linter
uv run ruff check src/

# Run type checker
uv run ty check src/

# Run tests
uv run pytest tests/ -v

License

MIT

---

Contributing & Git Hooks

This repo uses pre-commit to ensure code quality before every commit. The pre-commit hook will automatically run just_precommit and other checks.

Setup (one-time):

uv sync --dev
uv run pre-commit install

After setup, every commit will run the checks automatically. If any check fails, the commit will be aborted.

• To run the checks manually: uv run pre-commit run --all-files
• To update hooks: uv run pre-commit autoupdate

See .pre-commit-config.yaml for details.