Habitica Prioritization Matrix
Ranks Habitica todos using the pairwise comparison method: every item battles every other item head-to-head, the item with the most wins ranks highest. Ties are broken by the direct head-to-head result. Results are saved so future runs can do incremental re-ranking.
Usage
Full ranking (first time, or full re-rank)
uv run habitica-prioritizeIf --tags is omitted, the script prompts interactively with a list of available tags. Pass tags directly to skip the prompt:
# Single tag
uv run habitica-prioritize --tags Work
# Multiple tags (todos must match ALL specified tags)
uv run habitica-prioritize --tags Work Urgent
# No filter — rank all incomplete todos
uv run habitica-prioritize --tagsOptionally limit to top N items manually:
uv run habitica-prioritize --tags Work --limit 10If a full ranking would exceed 100 comparisons (more than 14 items), the script automatically warns and offers to trim.
When new tasks are found (K/R prompt)
When a saved ranking exists and new todos are detected, the script prompts:
Keep existing priorities (K) or re-prioritize everything from scratch (R)? (K/R):- K — compares each new item against every existing item only (new-vs-new and existing-vs-existing skipped)
- R — full pairwise comparison of all items from scratch
Check ranking status without running battles
uv run habitica-prioritize --tags Work --statusPrints a summary of battles answered, remaining, and new todos — then exits without prompting for any comparisons.
Incremental re-rank without prompting
Automatically selects K (keep existing priorities) without prompting:
uv run habitica-prioritize --incrementalApplying the ranking to Habitica
After ranking, the script prompts: Apply this order to Habitica? (Y/N). Answering Y reorders your tasks in the Habitica UI to match the ranking.
To skip the prompt and always apply automatically:
uv run habitica-prioritize --tags Work --reorderRequirements
Environment variables must be set:
HABITICA_USER_IDHABITICA_API_TOKEN
How it works
- Fetches all incomplete todos matching the given tags (AND logic — todos must have all specified tags)
- Walks you through every pair: "Which is higher priority? (1/2)"
- Tallies wins per item
- Produces a ranked list (#1 = most wins)
- Saves results to
~/.habitica-priority-rank.jsonfor incremental use
Running tests
uv run --extra dev pytest scripts/tests/ -vNotes
- N items = N*(N-1)/2 comparisons (10 items = 45, 14 items = 91, 15 items = 105)
- If comparisons would exceed 100, the script warns and offers to trim to 14 items automatically
- When new tasks are found and a saved ranking exists, choose K to compare only new vs. existing (skips new-vs-new and existing-vs-existing)
- Use
--incrementalto auto-select K without being prompted - Re-run without
--incrementaland choose R periodically for a fresh full re-rank