Note: Some features like Rank Analysis Reports are currently in beta testing and may not function correctly. Stick to the main rank tracking features for stable functionality.
Common Issue: When you download the ZIP file, it is named as "Ranked-Habit-Tracker-main". This stops the plugin from displaying the icons in the sidebar. You can simply fix it by renaming the folder to "ranked-habit-tracker" and then restarting Obsidian.
Ranked Habit Tracker is a plugin that tracks and ranks you based on your habits. This plugin contains RR (Rank Rating) that manages and decides your rank. The ranks take inspiration from Valorant.
This plugin can help you build habit for over a long term and keep you competitive. The gamified style can help you push yourself to the edge.
Download the entire repository and extract it to yourVault/.obsidian/plugins/ranked-habit-tracker. DO NOT download the releases.
You will need to set your habits in the properties in checkbox style. Numerical and alphabetical values will not work. Might add in the next update.
Disable all the default habits in the settings and add your own. You can name your habit anything. Then, you need to specify the folder your daily notes are stored in. Make sure your notes are saved in YYYY-MM-DD format. No other format will work. Add the field (or name of the property) you are tracking. You can customize RR per Day and Penalty per Day as per your liking. You can also change the Tracking Mode from Daily to Weekly.
You can open and see your rank by pressing a keyboard shortcut that you will have to set yourself from the commands. I have it set as Alt + V. You can set as per your comfort and requirements.
The plugin will open on the right sidebar of the Obsidian window. It will show you the rank your are on and how many RR are required to climb up the next rank.
When you skip a habit for more than 2 days, you will start gaining penalties (as per the value you set in Penalty per Day). Your RR count will decrease if you skip the habits for too long and thus your rank will decrease.
Grace Period Rules:
- Missing 1 day: Streak continues
- Missing 2 days: Streak continues
- Missing 3+ days: Streak breaks, penalty apply
Example:
- Complete activity Monday through Friday: 5-day streak
- Miss Saturday: Grace period (streak intact)
- Miss Sunday: Still within grace period (streak intact)
- Miss Monday: Streak broken on this day
Activity RR = Current Streak Length × RR per DayExample Calculation:
10-day streak = 10 days × 1 RR = 10 RRActivity RR = Consecutive Weeks Completed × RR per WeekExample Calculation:
- Completed Research in 5 consecutive weeks = 5 weeks × 7 RR = 35 RR
- If you skip a week, the streak breaks and starts over
- Install the plugin (the entire repository that includes the "assets") and enable it
- When you download the ZIP file, it is named as "Ranked-Habit-Tracker-main". This stops the plugin from displaying the icons in the sidebar. You can simply fix it by renaming the folder to "ranked-habit-tracker" and then restarting Obsidian.
- Open Settings → Ranked Habit Tracker
- Disable all default habits (or keep ones you want)
- Click "Add Custom Habit" for each habit you track
- Set your keyboard shortcut for "Open rank dashboard" (recommended:
Alt + V) - Press your shortcut to view your rank!
- Activities never started: 0 RR (no penalty)
- Activities with active streaks: Positive RR
- Activities with broken streaks: Net RR after penalties (may be negative)
Penalty Calculation:
Penalty Days = Days Since Last Completion - 2 (grace period)
Total Penalty = Penalty Days × Penalty Rate
Net RR = Earned RR from Past Streak - Total Penalty
Net RR is capped at: Maximum(-Earned RR, Net RR)Default penalty rate is -2 RR per day beyond grace period.
Example 1 - Standard Activity (Moderate Penalty):
- Built a 15-day workout streak: +15 RR earned
- Stopped working out for 6 days
- Penalty days: 6 - 2 = 4 days
- Penalty applied: 4 × 2 = -8 RR
- Net RR: 15 - 8 = +7 RR
Example 2 - No Fap (Moderate Penalty):
- Built a 20-day streak: +100 RR earned
- Broke streak, 5 days since last completion
- Penalty days: 5 - 2 = 3 days
- Penalty applied: 3 × 5 = -15 RR
- Net RR: 100 - 15 = +85 RR
Example 3 - Severe Penalty:
- Built a 10-day workout streak: +10 RR earned
- Stopped working out for 15 days
- Penalty days: 15 - 2 = 13 days
- Penalty applied: 13 × 2 = -26 RR
- Net RR: 10 - 26 = -16 RR
Your total RR is split into two components:
- Live RR: Current active streaks and penalties
- Historical RR: Immutable RR from past completed days outside current streaks
Total RR = Live RR + Historical RRHistorical RR Example:
- You built a 30-day workout streak and completed it
- Now you're on a fresh 5-day streak
- Historical RR: 25 days × 1 RR = 25 RR (immutable)
- Live RR: 5 days × 1 RR = 5 RR (can decay)
- Total: 30 RR
| Rank | Icon | Tier | RR Required |
|---|---|---|---|
| Unranked |  |
0 | 0 |
| Iron I |  |
1 | 50 |
| Iron II |  |
2 | 100 |
| Iron III |  |
3 | 150 |
| Bronze I |  |
4 | 200 |
| Bronze II |  |
5 | 250 |
| Bronze III |  |
6 | 300 |
| Silver I |  |
7 | 350 |
| Silver II |  |
8 | 400 |
| Silver III |  |
9 | 450 |
| Gold I |  |
10 | 500 |
| Gold II |  |
11 | 550 |
| Gold III |  |
12 | 600 |
| Platinum I |  |
13 | 650 |
| Platinum II |  |
14 | 700 |
| Platinum III |  |
15 | 750 |
| Diamond I |  |
16 | 800 |
| Diamond II |  |
17 | 850 |
| Diamond III |  |
18 | 900 |
| Ascendant I |  |
19 | 950 |
| Ascendant II |  |
20 | 1000 |
| Ascendant III |  |
21 | 1050 |
| Immortal I |  |
22 | 1100 |
| Immortal II |  |
23 | 1150 |
| Immortal III |  |
24 | 1200 |
| Radiant |  |
25 | 1250 |
The plugin includes a rank demotion grace period to prevent immediate rank loss:
Default Settings:
- Grace RR: 20 RR below rank threshold
- Grace Days: 3 days
How It Works:
- If your Total RR drops below your current rank threshold, a grace timer starts
- You have 3 days to recover back to the rank threshold
- If you're within 20 RR of the threshold, your rank is frozen during grace period
- After 3 days without recovery, demotion occurs
- A red warning indicator appears during the grace period
Example:
- You're Gold I (500 RR required)
- Your RR drops to 485 RR (15 below threshold, within 20 RR grace)
- Grace period activates: you have 3 days to get back to 500+ RR
- Your rank displays as Gold I with a "⬇ Rank under pressure" warning
- Progress bar turns red during grace period
You cannot freefall through ranks. If your RR drops significantly, your effective RR is clamped at the previous rank's threshold:
Example:
- You're at Gold II (550 RR)
- Penalties drop you to 470 RR
- Your effective RR is clamped at 500 RR (Gold I threshold)
- You display as Gold I, not Bronze III
- Progress bar shows 0% toward Gold II
The main dashboard displays:
- Current Rank: Visual rank icon with name
- Total RR: Your accumulated rating points
- Progress Bar: Visual progress to next rank (color-coded by tier)
- RR Needed: Exact points required for next rank
- Demotion Warning: Alert if in grace period
- Active Penalties: List of activities currently penalized
Opening the Rank View:
- Command Palette: "Open rank dashboard"
- Appears in right sidebar
Add unlimited custom habits beyond the default 13:
Configurable Settings:
- Habit name
- Folder path (where daily notes are stored)
- Property name (checkbox field in frontmatter)
- RR per day/week
- Penalty per day (for daily tracking)
- Tracking mode (daily or weekly)
- Enable/disable toggle
How It Works:
- Go to plugin settings
- Click "Add Custom Habit"
- Configure folder, property, and RR values
- The habit immediately starts tracking
From GitHub Releases:
- Download the entire repository including the "assets" folder
- Extract to
.obsidian/plugins/ranked-habit-tracker/ - Restart Obsidian
- Enable in Settings → Community Plugins
Manual Installation:
- Clone this repository into
.obsidian/plugins/ - Run
npm installandnpm run build - Restart Obsidian
- Enable in Settings → Community Plugins
- Obsidian
- Daily notes with YYYY-MM-DD format filenames
- Checkbox properties in note frontmatter
The plugin expects daily notes in specific folders with checkbox properties:
Example Folder Structure:
01 Daily Journal/
2024-12-20.md
2024-12-21.md
02 Workout/
2024-12-20.md
2024-12-21.md
03 Guitar Practice/
2024-12-20.md
...Example Daily Note (Frontmatter):
---
DJournal: true
Workout: true
Guitar: false
Python: true
Cardio: true
Reading: false
MasturbationAvoided: true
GTG: true
Study: true
Research: true
Gaming: false
waterPlants: true
Medicine: true
---
# 2024-12-20
Your daily note content...Edit main.ts to customize:
RR Values:
{
name: "Workout",
folder: "02 Workout",
field: "Workout",
rrPerDay: 2, // Change from 1 to 2
penaltyPerDay: 3 // Change from 2 to 3
}Grace Period:
const DEFAULT_SETTINGS: TrackRankSettings = {
rankGraceRR: 30, // Change from 20
rankGraceDays: 5, // Change from 3
...
}| Command | Description |
|---|---|
| Open rank dashboard | Opens main rank view |
| Capture rank snapshot | Saves current state |
| Open rank stats (BETA) | Views snapshot history |
| Generate rank analysis (last 30 days) (BETA) | Creates 30-day report |
| Generate rank analysis (BETA) | Creates custom report |
Fastest Path to Higher Ranks:
- Prioritize high-value activities (No Fap = 5 RR/day)
- Maintain multiple simultaneous streaks
- Never let daily streaks exceed 2-day grace period
- Build long streaks before any planned breaks
- Weekly activities provide steady RR with no penalty risk
RR Efficiency:
- Maximum daily RR potential: 18 RR (all 13 activities daily)
- Maximum weekly RR potential: 133 RR per week (18 × 7 + 7 Research)
- No Fap contributes 27.8% of maximum daily RR
- Research provides 5.3% of maximum weekly RR for minimal effort
Recovery Strategy:
- Resume broken activities immediately to minimize penalty accumulation
- Each additional day beyond grace period increases penalty
- Consider disabling activities you know you'll skip (preserves frozen RR)
- Weekly tracked activities have no penalties—great for irregular habits
Critical Thresholds:
- Standard activity: Every 2 penalty days negates 1 day of past streak (2:1 ratio)
- No Fap: Every 1 penalty day negates 1 day of past streak (1:1 ratio)
Approximate Timeline (assuming 100% consistency):
- Iron I to Bronze III: ~14 days
- Iron I to Silver III: ~22 days
- Iron I to Gold III: ~30 days
- Iron I to Platinum III: ~39 days
- Iron I to Diamond III: ~47 days
- Iron I to Immortal III: ~64 days
- Iron I to Radiant: ~67 days
Note: These estimates assume perfect daily completion of all activities with no penalties applied.
The system queries markdown files in your vault folders based on:
- Filename format:
YYYY-MM-DD.md - Frontmatter properties: Boolean checkbox fields
- Folder structure: Configurable per activity
The ranking system recalculates automatically when:
- Metadata cache changes (checkbox toggled in any note)
- Settings are modified
- Dashboard is refreshed
Debouncing (300ms) prevents excessive recalculation.
- Daily streaks count backwards from most recent completion
- Weekly streaks use ISO week numbers (Monday start)
- Grace period is strict: exactly 2 calendar days
- Historical RR excludes current streak days (prevents double-counting)
All plugin data is stored in:
.obsidian/plugins/ranked-habit-tracker/data.json
This includes:
- Enabled/disabled activities
- Custom habits configuration
- Rank grace settings
- Activity snapshots (frozen RR)
- Rank snapshot history
The following features are currently in testing and may not work as expected:
Generate detailed activity reports with visual heatmaps. This feature is experimental and may have issues.
Commands:
- "Generate Rank Analysis (Last 30 Days)" - Quick 30-day report
- "Generate Rank Analysis" - Custom date range
Known Issues:
- Report generation may fail for large date ranges
- Heatmap visualization may not render correctly
- Some activities may not appear in reports
Note: This feature is under active development. Use at your own risk and please report any bugs you encounter.
Q: Can my Total RR go negative?
A: Yes, Total RR can go negative if accumulated penalties exceed earned RR. However, you'll remain at Iron I (0 RR) until Total RR becomes positive again.
Q: What happens if I rank up then immediately break streaks?
A: Your rank will decrease if penalties push your Total RR below the current rank threshold. The grace period gives you 3 days to recover.
Q: Do penalties compound over time?
A: Yes, each additional day beyond the grace period adds more penalty RR. There is no cap—penalties can exceed earned RR.
Q: Is there a maximum RR cap?
A: No, you can accumulate RR indefinitely beyond Radiant (1200 RR).
Q: How do I add activities from different folders?
A: Use Custom Habits in settings. You can track any checkbox property from any folder.
Q: Can I track the same property from multiple folders?
A: No, each habit tracks one folder/property combination. Create separate custom habits if needed.
Q: What happens to my RR if I disable an activity?
A: The plugin captures a "snapshot" of the activity's current RR (both live and historical) and adds it to your Historical RR. Your Total RR is preserved. If you re-enable the activity, it starts tracking from a fresh streak.
Q: Can I change RR values after I've started tracking?
A: Yes, but it only affects future calculations. Past Historical RR remains unchanged.
Q: How do I backup my progress?
A: Copy the data.json file from the plugin folder. All settings, snapshots, and grace period state are stored there.
Q: Can I use weekly tracking for activities that need daily consistency?
A: Not recommended. Weekly tracking is best for activities like "Research" or "Meal Prep" where frequency matters less than regular completion.
Q: What's the difference between Live RR and Historical RR?
A: Live RR comes from your current active streaks (can decay with penalties). Historical RR is immutable and comes from past completed days outside your current streaks. Total RR = Live RR + Historical RR.
Plugin Version: 2.0
Last Updated: December 2025
Compatibility: Obsidian v1.10.6
Major Features in v2.0:
- Weekly tracking mode (in addition to daily)
- Rank demotion grace period (3 days + 20 RR buffer)
- Demotion floor (prevents rank freefall)
- Custom habits with unlimited configuration
- Real-time dashboard updates
Inspired by Valorant's competitive ranking system. Rank icons from Valorant (Riot Games).