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-prioritize

If --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 --tags

Optionally limit to top N items manually:

uv run habitica-prioritize --tags Work --limit 10

If 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 --status

Prints 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 --incremental

Applying 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 --reorder

Requirements

Environment variables must be set:

HABITICA_USER_ID
HABITICA_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.json for incremental use

Running tests

uv run --extra dev pytest scripts/tests/ -v

Notes

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 --incremental to auto-select K without being prompted
Re-run without --incremental and choose R periodically for a fresh full re-rank