Automate project plans written in Markdown. Generate a clean, gantt-like timeline from your phases and milestones, and keep progress indicators up to date with a single command.
- Initialize a new plan from a template
- Parse phases and milestones from the plan
- Generate/refresh a gantt-like "Project Timeline (Phases)" section
- Generate/refresh "Milestone Status Overview" graph showing status distribution
- Current-date marker with clamping to last milestone date
- Global and per-phase percentages showing actual vs should-be
- Flexible baseline vs current planning basis selection for timeline comparison
pip install pixel-planner- Python 3.9+ required
- Clone this repository and use
python3 scripts/pixel_planner.py
- Create a plan from the template
# If installed via pip/brew:
pixel-planner init --out Project-Plan.md --project "My Project"
# If using cloned repository:
python3 scripts/pixel_planner.py init \
--template templates/pixel-planner-phase-template.md \
--out Project-Plan.md \
--project "My Project"-
Edit your plan: fill the phases and milestone tables
-
Generate or refresh the timeline
- In place (recommended):
# If installed via pip/brew:
pixel-planner timeline --in Project-Plan.md --in-place --basis current
# If using cloned repository:
python3 scripts/pixel_planner.py timeline --in Project-Plan.md --in-place --basis current- Include milestone status overview graph:
pixel-planner timeline --in Project-Plan.md --in-place --basis current --include-status- To a separate file using baseline dates:
pixel-planner timeline --in Project-Plan.md --out Project-Plan.out.md --basis baseline --version v1.0- Generate as-of a specific date (for reproducible timelines):
pixel-planner timeline --in Project-Plan.md --in-place --basis current --date 2025-03-02- A complete example is included:
Sample-Project-Plan.md - Regenerate its timeline anytime:
# If installed via pip/brew:
pixel-planner timeline --in Sample-Project-Plan.md --in-place --basis current --include-status
# If using cloned repository:
python3 scripts/pixel_planner.py timeline --in Sample-Project-Plan.md --in-place --basis current --include-status- This project was built using a vibe-coding (AI-assisted pair programming) workflow.
- The only manually created artifact at the start was the first Markdown template; everything else (the Python CLI, timeline logic, clamping and percentage rules, sample plan, tests, CI, and repo docs) was iteratively generated and refined in-session.
My take: this approach fits this tool very well. Rapid, iterative edits plus immediate feedback make it easy to converge on the exact timeline semantics and formatting you want. The added tests and CI balance speed with correctness and maintainability. For larger systems, I’d complement this with brief design docs and peer reviews, but for a focused automation like Pixel Planner, vibe-coding was a strong choice.
-
Timeline section
- There must be a heading named exactly
## Project Timeline (Phases) - The content under it is a fenced block (
text ...). The script fully rewrites this block.
- There must be a heading named exactly
-
Phase sections
- Each phase must use a heading of the form:
## Phase 01 – Phase Name(hyphen-also accepted instead of the en dash–).
- Each phase must use a heading of the form:
-
Milestone table under each phase
- Columns (any alignment/width). Names are matched case-insensitively by meaning:
- Milestone | Description | Status | Baseline Plan | Current Plan | Assignee | Comments
- Dates must be ISO
YYYY-MM-DD. Values likeN/A,NA,TBDare treated as empty. - A milestone is counted as executed only when
StatusisDone(case-insensitive).
- Columns (any alignment/width). Names are matched case-insensitively by meaning:
-
Bars and weeks
- Each
■represents one calendar week. Bars are aligned over a global week grid spanning the earliest to latest plan dates (based on--basis). - A vertical
|marks the effective date week. - Bars always close with a
]and are clipped properly at the right edge.
- Each
-
Effective date (header arrow)
- The header shows:
┌─→ YYYY-MM-DD (X% / Y%) - The effective date is today, but if today is beyond the last milestone date (across all phases), it is clamped to that last milestone date.
- The header shows:
-
Basis (which plan dates are used)
--basis current(default): position bars and compute "should-be" from Current Plan dates. Shows activity evolution percentages.--basis baseline: use Baseline Plan dates instead. Shows clean timeline bars without activity evolution percentages.- This separation allows you to maintain both your original baseline and revised current plans, enabling comparison between planned vs actual timeline evolution.
- You can generate timelines using either version independently, making it easy to track scope changes and schedule adjustments over time.
Note: Activity evolution percentages are only shown for --basis current timelines. Baseline timelines show clean bars without percentages.
-
Header percentages (global):
X% / Y%- X% = executed/total across all milestones (executed = count of
Done). - Y% = planned-by-effective-date/total across all milestones, based on the chosen basis.
- X% = executed/total across all milestones (executed = count of
-
Per-phase percentages:
X% / Y%- X% = executed_in_phase / total_in_phase.
- Y% = planned_by_effective_date_in_phase / total_in_phase, using the chosen basis.
-
Important rule: "planned-by-effective-date" uses a strict comparison of planned date < effective date. Milestones due today are counted as should-be tomorrow (after the day passes).
-
Direction indicator: ▲ if executed ≥ should-be; otherwise ▼ (for current timelines only).
When using --include-status, a status graph is generated showing milestone distribution:
- Each ■ represents 10% of total milestones
- Status names are automatically aligned for readability
- Sorted by count (descending), then alphabetically
- Backlog : 14 → [■ ■ ■ ■ ■ ■ ■ ■] 82%
- Done : 01 → [■] 6%
- In Progress : 01 → [■] 6%
- Ready for Review : 01 → [■] 6%
┌─→ 2025-03-02 (33% / 67%)
- Phase 01 – Install Infrastructure ▲ W 05-08 2025-01-31 to 2025-02-20 → [■ ■ ■ ■] 50% / 100%
- Phase 02 – Deploy new App ▼ W 09-09 2025-03-02 to 2025-03-02 → | [■] 0% / 0%- Phase 01 – Install Infrastructure ▲ W 05-08 2025-01-31 to 2025-02-20 → [■ ■ ■ ■]
- Phase 02 – Deploy new App ▲ W 09-09 2025-03-02 to 2025-03-02 → [■]
- Keep the timeline heading spelled exactly as
## Project Timeline (Phases) - Keep the status heading spelled exactly as
## Milestone Status Overview(when using--include-status) - Use correct phase heading format:
## Phase <number> – <name>(or-) - Use ISO dates. If a phase has no valid dates for the selected basis, its bar may be empty but the line still renders.
- Only
Donemarks a milestone as executed. - The
Weekcolumn is deprecated and ignored in parsing; you can safely remove it.
- Timeline didn't update
- Check the heading and code fence (```text) under the timeline section
- Status overview didn't update
- Check the heading and code fence (```text) under the status section
- Ensure you used
--include-statusflag
- A phase didn't show a bar
- Ensure it has at least one valid planned date for the chosen basis
- Percentages look wrong
- Verify
Statusvalues and planned dates; items due today don't count as should-be yet
- Verify
git clone https://github.com/prometh-sh/pixel-planner.git
cd pixel-planner
pip install -r requirements-dev.txt
pip install -e .pytest -q # Run all tests
ruff check . # Lint code
mypy pixel_planner # Type checkSee RELEASING.md for the automated release process.
Improvements welcome! Please:
- Keep changes small and readable
- Add tests for new functionality
- Follow existing code style
- Submit pull requests for review
Apache-2.0. See LICENSE. A NOTICE file is included for attribution.