pm-gantt-chart

Gantt chart renderer and multi-format exporter for pm-cli.

Renders your pm items as a week-by-week timeline in the terminal — grouped by milestone, sprint, release, assignee, status, type, or tag — and exports the same chart to Mermaid gantt, standalone HTML, ASCII, a CSV schedule, or structured JSON. Can compute and highlight the critical path (longest dependency chain), and run dependency-aware scheduling that derives each item's start/end from its blocked-by chain plus estimates.

Example output

pm gantt  •  8 weeks from 2026-06-01  •  critical path marked
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
GROUP               ITEM                       S  W1      W2      W3      W4      W5      W6      W7      W8
──────────────────────────────────────────────────────────────────────────────────────────
                                                  Jun  1  Jun  8  Jun 15  Jun 22  Jun 29  Jul  6  Jul 13  Jul 20
──────────────────────────────────────────────────────────────────────────────────────────
S1                  *Build endpoint           ▶   ▓▓      ▓▓
                    *Design API               ✓   ▓▓
S2                  *Release                   ○   ▓▓      ▓▓      ▓▓      ▓▓
                    Write docs                ○   ░░      ░░      ░░
                    *Integration tests        ○   ▓▓      ▓▓      ▓▓
(no milestone)      Backlog grooming          ○   ░░      ░░
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Legend: ██ in_progress/blocked  ░░ open/planned  ▓▓ critical-path (*)  ·· undated  S: ▶in_progress  !blocked  ✓closed  ○open

Installation

pm install unbraind/pm-gantt-chart

Or from a local clone:

pm install ./path/to/pm-gantt-chart

Usage

Terminal chart — pm gantt

# Default: 8 weeks, grouped by milestone, all statuses
pm gantt

# Show 12 weeks
pm gantt --weeks 12

# Group by sprint / release / assignee / status / type
pm gantt --group-by sprint
pm gantt --group-by release
pm gantt --group-by assignee
pm gantt --group-by status

# Show only in-progress items
pm gantt --status in_progress

# Anchor the window at a specific date, or clip it with --to
pm gantt --from 2026-06-01 --weeks 16
pm gantt --from 2026-06-01 --to 2026-08-01

# Dependency-aware scheduling: derive start/end from blocked-by chains + estimates
pm gantt --schedule
pm gantt --schedule --default-duration 3

# Compute & mark the longest dependency chain
pm gantt --critical-path

# Show only the critical path (great paired with --schedule)
pm gantt --critical-only --schedule

# Show each item's % complete on its bar
pm gantt --progress
# (or use the --show-progress alias)
pm gantt --show-progress

# Overlay fixed release/deadline dates as labeled vertical markers
pm gantt --milestones "v1.0=2026-06-30,v1.1=2026-08-15"

Export — pm gantt export

# Mermaid `gantt` diagram (default format) to stdout
pm gantt export

# Mermaid to a file
pm gantt export --format mermaid --output roadmap.mmd

# Standalone, self-contained HTML
pm gantt export --format html --output roadmap.html

# Scalable Vector Graphic (SVG) — a self-contained vector render of the chart.
# Use --width to request the canvas width in pixels (default 1000, clamped 320..8192).
pm gantt export --format svg --width 1600 --output roadmap.svg

# Plain ASCII (the same chart `pm gantt` prints)
pm gantt export --format ascii --output roadmap.txt

# CSV schedule: id,title,start,end,duration_days,slack_days,deps,status,critical,progress_percent,overdue,off_window
pm gantt export --format csv --schedule --output schedule.csv

# Structured JSON schedule for agents / programmatic consumers
pm gantt export --format json --schedule --output schedule.json

# Export honors the same shaping flags (including --schedule / --critical-only)
pm gantt export --format html --group-by assignee --critical-path --weeks 12 --output team.html
pm gantt export --format mermaid --schedule --group-by sprint --output plan.mmd

The exporter writes to the file given by --output, or prints to stdout when omitted (handy for piping into a Mermaid live editor).

Options

Both pm gantt and pm gantt export accept the shaping flags:

| Flag | Values | Default | Description | |------|--------|---------|-------------| | --weeks <n> | 1–52 | 8 | Number of weeks to display (ignored when --to is set) | | --group-by <field> | milestone | sprint | release | type | assignee | status | tag | milestone | How to group items into rows | | --status <filter> | open | in_progress | blocked | closed | canceled | draft | all | all | Filter items by status | | --from <iso> | YYYY-MM-DD | current week | Anchor the chart window at this date | | --to <iso> | YYYY-MM-DD | — | Clip the window to end at this date (derives the week count, overriding --weeks) | | --schedule | flag | off | Dependency-aware scheduling: derive start/end from blocked-by chains + estimates | | --default-duration <days> | integer ≥ 1 | 5 | Fallback duration for items with no estimate under --schedule | | --critical-path | flag | off | Compute & mark the longest dependency chain | | --critical-only | flag | off | Show only items on the critical path (implies critical-path computation) | | --progress | flag | off | Show each item's % complete on its bar | | --show-progress | flag | off | Alias for --progress — show each item's % complete on its bar | | --width <px> | integer ≥ 1 | 1000 | Requested render width in pixels for SVG and HTML (clamped 320..8192; SVG expands when needed to preserve readable week columns; ignored by ASCII/Mermaid/CSV/JSON) | | --milestones <list> | name=YYYY-MM-DD,… | — | Draw fixed release/deadline dates as labeled vertical markers on the timeline |

pm gantt export adds:

| Flag | Values | Default | Description | |------|--------|---------|-------------| | --format <fmt> | mermaid | html | svg | ascii | csv | json | mermaid | Output format | | --output <file> | path | stdout | File to write (prints to stdout if omitted) |

json emits the computed schedule as structured, machine-readable data — window, options, a summary (project span, critical-path length, total task-days, per-group workload), milestones, and an items[] array where each entry carries id, title, type, status, group, ISO start/end, durationDays, slackDays, progress, critical, overdue, infeasible, offWindow, and gating deps. Unlike pm --json gantt (which returns the rendered ASCII chart plus summary counts), this is the full per-item plan, so agents and scripts can reason about the schedule without parsing a chart or CSV. Output is deterministic (no embedded wall-clock), so identical input produces byte-identical JSON. Pair with --schedule for dependency-derived dates and slack.

csv emits a schedule table: id,title,start,end,duration_days,slack_days,deps,status,critical,progress_percent,overdue,off_window (deps = space-separated blocking ids). Pair it with --schedule for dependency-derived dates and slack. slack_days is the total float in days (only populated under --schedule; blank otherwise): 0 marks a critical-path item, a positive value is how many days the task can slip without delaying the project, and a negative value means the plan is already late for a downstream deadline. The trailing risk columns make the CSV useful directly in spreadsheets and portfolio reports: critical/overdue are yes/no, progress_percent is 0..100, and off_window distinguishes before, after, and undated rows.

svg emits a self-contained, scalable vector graphic of the chart — the same grouped rows, week columns, status-colored bars, critical-path highlighting, overdue markers, off-window hints, today rule, milestone diamonds, and --progress fill as the HTML render, but as resolution-independent SVG primitives. Use --width to request the canvas width in pixels (default 1000, clamped to 320..8192). For long timelines the SVG expands beyond that request rather than clipping the chart, preserving a readable 24px minimum per week. The output is a single <svg> document (with an <?xml?> prologue) suitable for embedding in docs, slides, or websites, or for rendering at any zoom level without pixelation.

Slack / float, critical path & infeasible deadlines

Under --schedule, a backward pass (classic CPM) computes each item's latest feasible start/finish from the project end and any downstream deadlines, then derives total slack = latest start − earliest start:

• 0 slack → the item is on the critical path; any slip delays the project.
• positive slack → the item can slip that many days harmlessly.
• negative slack → the item's required start (to hit a downstream deadline) is before its earliest feasible start. The plan is already late. These items are listed in a WARNING: block on stderr by both pm gantt and pm gantt export, and flagged per-task in the JSON result (tasks[].slack_days, tasks[].infeasible, plus infeasibleCount / warnings).

Preflight data-sanity gate

Before rendering, both pm gantt and pm gantt export run a preflight data-sanity gate so bad data surfaces early instead of producing a silently-confusing chart. It splits problems into two tiers:

• Hard-fail (blocks, non-zero exit) — a dependency cycle. A cycle has no valid topological order, so dependency-aware scheduling is impossible and any chart drawn from it would be plausible-looking but wrong. The command aborts with a clear error naming the full cycle path, e.g.:

  gantt: 1 fatal data problem(s) make scheduling impossible:
    • dependency cycle: pm-a "Design" → pm-b "Build" → pm-a "Design"
  Resolve the dependency cycle(s) above and re-run.

• Warn (non-blocking, stderr; chart still renders, exit 0) — soft issues that still yield a useful chart: a deadline that precedes the item's own start date, and an implausibly large estimate (over ~2000h, almost always a minutes-vs-hours unit error). These print a NOTE: block on stderr and are suppressed under --json to keep machine-readable output clean.

Fully valid data produces no warnings and no block. (Infeasible/unreachable downstream deadlines are a separate, lighter signal — they are flagged in the schedule's backward pass rather than by this gate; see above.)

TODAY marker (all formats)

The current week is indicated in every format, shown only when "today" falls inside the chart window:

• ASCII — a ▼TODAY caret under the week column that contains the current date.
• Mermaid — a %% today: <date> comment.
• HTML — the matching week column is highlighted with a red vertical rule and a ▼ today label in the header.

--milestones — fixed release/deadline dates

Items are scheduled work; milestones are immovable calendar targets (a release, a launch, a contractual deadline). In cross-functional views that aren't grouped by milestone, those dates are otherwise invisible. --milestones overlays them as labeled vertical markers so deadline pressure is obvious at a glance.

Pass a comma-separated list of name=YYYY-MM-DD entries:

pm gantt --milestones "v1.0=2026-06-30,v1.1=2026-08-15"

• ASCII — a ▼<name> caret in the week column the milestone lands in (parity with the ▼TODAY marker). Multiple milestones in the same week are comma-joined (▼v1.0,beta).
• Mermaid — a dedicated section Milestones with native zero-duration :milestone markers on the exact date, so they render as the diamond marker.
• CSV — appended rows (id=milestone:<name>, status=milestone, start=end=date) so the dates round-trip alongside the schedule.

Milestones outside the rendered window are ignored on the chart/Mermaid output, with a one-line note on stderr (CSV still includes them so the data round-trips). Malformed entries (missing =, empty name, or a non-ISO date) fail cleanly with a usage error rather than crashing. The same flag is honored by pm gantt export.

--progress — % complete on bars

--progress (opt-in) renders each item's completion ratio on its bar. The ratio is derived deterministically from available pm signals:

• closed / canceled → 100%
• an explicit meta.progress / meta.percent_complete number (a 0..1 fraction or a 0..100 percent) → honored verbatim
• an acceptance-criteria checklist in the body (- [x] vs - [ ]) → checked / total
• in_progress with no other signal → 50% (a "halfway" default); blocked → 25%
• everything else (open / draft) → 0%

It surfaces as a trailing NN% plus a coarse fill glyph in ASCII (·· 0% · ░░ 25% · ▓░ 50% · ▓▓ 75% · ██ 100%), as a %% tN progress: comment in Mermaid (the diagram has no native per-task percent field), as a width-sized fill overlay plus a NN% label in HTML, and as progress_percent in CSV.

Overdue / deadline-risk highlighting

Items whose deadline is before today and that are not closed/canceled are flagged automatically (no flag needed):

• ASCII — a trailing ‼ OVERDUE marker on the row.
• Mermaid — the task carries the crit tag (the diagram's deadline-risk styling) plus an %% overdue: comment.
• HTML — the bar gets a red striped fill, the due date turns red, and the row label shows a ‼ overdue marker.

Overdue items are also counted in the JSON result (overdueCount, overdue[]) and listed in a NOTE: block on stderr (suppressed under --json).

Off-window vs. undated items

A genuinely undated item (no dates at all) and an item whose dates fall entirely outside the chart window used to look identical (both ··). They are now distinguished:

• undated → ·· (ASCII) / a hatched cell (HTML).
• off-window earlier → ←· (ASCII) / a ← hint in the first column (HTML).
• off-window later → ·→ (ASCII) / a → hint in the last column (HTML).

The JSON result reports offWindowCount and undatedCount. Mermaid is unaffected (it always renders real dates).

ASCII TODAY marker

The terminal chart draws a ▼TODAY caret under the week column that contains the current date (parity with the Mermaid %% today: marker and the HTML today column), shown only when "today" falls inside the chart window.

HTML summary & assignee workload

The HTML export ends with a Summary footer — project span (start → end and day count), critical-path length, and total task-days. When exported with --group-by assignee, an additional Assignee workload table lists each assignee's total task-days (descending).

How it works

• Columns — each column is one calendar week, starting from the Monday of the anchor week (--from, or the current week by default). --to clips the window and derives the week count.
• Rows — items are grouped by the chosen field; items with no value land in a (no milestone) / (no sprint) / (no release) / (no type) / (unassigned) / (no tag) group. --group-by status groups by lifecycle status.
• Bars (default) — a bar spans from the item's created_at to its deadline. If only a deadline is known, a one-week bar ending on it is shown. Items with no dates at all are shown as ·· (undated).
• Bars (--schedule) — a forward pass schedules each item to start the day after the latest item it is blocked_by finishes. Duration comes from estimated_minutes (8h workday, rounded up to whole days) or --default-duration. Items with a reachable deadline are back-anchored to end on it. The chain ordering, not the calendar, drives the bars — a late chain can push a dependent past its deadline, which is exactly what a schedule should expose.
• Critical path — with --critical-path (or --critical-only), the longest chain of dependencies edges is computed (cycle-safe), its items prefixed with * and drawn with ▓▓ bars. Ties break toward the chain with the latest final deadline. --critical-only drops every off-path item.
• Symbols — ██ = in_progress/blocked, ░░ = open/planned, ▓▓ = critical path, ·· = undated, ←· / ·→ = off-window (dates earlier / later than the window), ‼ OVERDUE = past deadline & not closed.

Item fields used

Items are read via pm list-all --json --include-body.

| Field | Used for | |-------|----------| | title | Row label | | status | Bar style and status symbol; also used with --status filter | | deadline (or legacy due_date) | Right edge of the bar; back-anchor target under --schedule | | created_at | Left edge of the bar (default mode) | | estimated_minutes | Task duration under --schedule (8h workday) | | sprint / release / milestone | Group key for --group-by milestone (default), sprint, release | | type | Group key for --group-by type | | assignee | Group key for --group-by assignee | | status | Group key for --group-by status; also bar style | | tags[0] | Group key for --group-by tag | | dependencies[].id (kind blocked_by) | Edges used for scheduling and the critical path |

Development

npm install      # install dev dependencies
npm run build    # build TypeScript → dist/
npm test         # build + run smoke tests
npm run check    # tsc --noEmit
pm install .     # load the built extension locally

Requirements

• pm-cli >=2026.7.29
• Node.js >=22.18.0

License

MIT

Release Automation

This package is release-ready for GitHub, npm, and Bun-compatible installs. CI runs type checking, build, production dependency audit, package packing, Bun install verification, and pm-changelog validation. The daily release workflow publishes only when commits exist after the latest release tag and uses pm-changelog to generate CHANGELOG.md and GitHub release notes.

Multi-agent merge safety

This repo tracks its project management in .agents/pm/ and ships a committed .gitattributes that maps those tracker artifacts to pm-cli's field-aware Git merge drivers, so concurrent-branch tracker edits merge cleanly instead of hard-conflicting. The driver definitions live in per-clone Git config; npm install / npm ci wires them automatically via the prepare script (a portable Node guard, scripts/prepare-merge-driver.mjs: it runs pm merge install only when the pm CLI is on PATH, and no-ops cleanly otherwise so production / --omit=dev installs are not broken; being Node-based it behaves identically on POSIX shells and Windows cmd.exe). To (re)run manually: npm run merge:install.

After merging a branch that touched .agents/pm/, reconcile any residual history-hash drift with pm merge reconcile (pm-cli ≥ 2026.7.22): preview with pm merge reconcile --dry-run, apply with pm merge reconcile --message "post-merge reconcile", then confirm with pm validate, which scans the whole tracker and flags remaining history drift across every affected item (pm merge reconcile itself lists each affected stream in its output; pm history --verify <id> spot-checks one item). The field-aware driver already unions every author's content, so reconcile only re-greens the hash chain (no data loss) — see the authoritative pm-cli merge-safety guide. The older blunt pm history-repair --all remains available as a lower-level primitive.