Regen

Regen is an Obsidian Community Plugin starter for a local, gamified work-rhythm HUD.

Work. Recover. Continue.

Regen helps you balance focus sessions with recovery, hydration, meals, movement and eye breaks. It is intentionally advisory: it never blocks work, never removes XP, never removes levels and never shames missed days.

Regen is a gamified productivity and work-rhythm tool. Health, Stamina, Hydration and Food are fictional game indicators based on configured routines and activity. Regen does not provide medical advice.

Features

• Health, Stamina, Hydration and Food game bars
• XP and progressive levels
• Daily quests and weekly goals
• Work sessions with idle and sleep-gap handling
• Microbreaks, recovery breaks, long breaks and movement quests
• Hydration, meal and snack check-ins with cooldowns
• Statusbar HUD: full, compact and minimal
• Regen dashboard view
• Settings tab with safe defaults
• 25 presentation-only skins
• JSON and CSV export commands
• First-run onboarding
• Snoozeable reminders
• Combined recovery reminder objectives
• Daily, weekly and monthly dashboard statistics
• JSON import and reset commands
• Dark mode, light mode and reduced-motion friendly CSS
• Local-only data storage

Installation

Regen is not listed in the Obsidian Community Plugin browser yet. Until it is accepted there, use one of the testing installation methods below.

Option 1: Install With BRAT

BRAT is the easiest way to install and update beta Obsidian plugins from GitHub.

1. In Obsidian, open Settings -> Community plugins.

2. Turn off Restricted mode if it is still enabled.

3. Click Browse and install BRAT.

4. Enable BRAT.

5. Open the command palette.

6. Run BRAT: Add a beta plugin for testing.

7. Paste this repository URL:

   https://github.com/loopman90/regen
   

8. Confirm the installation.

9. Go back to Settings -> Community plugins.

10. Enable Regen.

11. Run Regen: Open from the command palette.

Option 2: Manual Install From GitHub Release

Use this if you do not want to use BRAT.

1. Download the latest release:

   github.com/loopman90/regen/releases/latest

2. Download these three files from the release assets:

   main.js
   manifest.json
   styles.css
   

3. Open your Obsidian vault folder on your computer.

4. Inside the vault, create this folder if it does not already exist:

   .obsidian/plugins/regen/
   

5. Put the three downloaded files into that folder:

   .obsidian/plugins/regen/main.js
   .obsidian/plugins/regen/manifest.json
   .obsidian/plugins/regen/styles.css
   

6. Restart Obsidian, or reload plugins from Settings -> Community plugins.

7. Enable Regen.

8. Run Regen: Open from the command palette.

Option 3: Build From Source

Use this if you want to develop Regen locally.

1. Clone the repository:

   git clone https://github.com/loopman90/regen.git
   cd regen
   

2. Install dependencies:

   npm install
   

3. Build the plugin:

   npm run build
   

4. Copy the built plugin files into your vault:

   .obsidian/plugins/regen/
   

   Required files:

   main.js
   manifest.json
   styles.css
   

5. Enable Regen in Obsidian.

Updating

If you installed with BRAT, use BRAT: Check for updates to all beta plugins.

If you installed manually, download the latest release assets again and replace the old files in:

.obsidian/plugins/regen/

Troubleshooting

• If Regen does not appear, make sure the folder name is exactly regen.
• If Obsidian says the plugin failed to load, confirm that main.js, manifest.json and styles.css are all in the same folder.
• If Obsidian reports a version mismatch, use a release tag that exactly matches manifest.json, such as 0.3.0 rather than v0.3.0.
• If the dashboard does not open, run Regen: Open Regen from the command palette.

Usage

Open the command palette and run Regen: Open.

Common commands:

• Start Work Session
• Start Focus Session
• Start Microbreak
• Start Recovery Break
• Register Drink
• Register Breakfast, Lunch or Dinner
• Register Snack
• Start Movement Quest
• End Workday
• Export Data as JSON
• Export Stats as CSV

Presets

The default mode is Balanced:

• Eye break every 20 minutes
• Micro movement around 30 minutes
• Focus nudge around 50 minutes
• Recovery prompt around 60 minutes
• Stronger recovery nudge around 75 minutes
• Hydration around 75 minutes, with randomization
• Breakfast, lunch and dinner windows

Other modes included in the settings model:

• Relaxed
• Pomodoro
• Deep Work
• Hardcore
• Custom

Skins

Regen includes 25 presentation-only skins. Skins can change color, spacing and HUD feel, but never game logic.

Privacy

Regen is built to work completely locally:

• No account required
• No AI required
• No cloud backend
• No advertising
• No telemetry by default
• No reading content from other applications

The Track activity outside Obsidian setting is off by default. The current implementation falls back to Obsidian activity.

Development

npm install
npm run dev

Run a production build:

npm run build

Versioning And Releases

Regen uses semver-style versions such as 0.4.1.

For every release, update these files to the same version:

• manifest.json
• package.json
• versions.json
• RELEASE_NOTES.md
• CHANGELOG.md

Then create and push a matching tag. Obsidian expects the tag to match manifest.json exactly, without a leading v.

git tag 0.4.1
git push origin main --tags

GitHub Actions will build the plugin and publish a release with the Obsidian plugin assets:

• main.js
• manifest.json
• styles.css

Tests

Run the local test suite:

npm test

The release workflow runs tests before publishing Obsidian assets.

Roadmap

V1 foundation:

• Richer reminders and snooze escalation
• Onboarding flow
• Weekly and monthly statistics views
• Import with overwrite confirmation
• Safer file overwrite handling for exports

V1.1+ ideas:

• Focus Boss
• Mood check-ins
• Local pattern recognition
• Daily Notes integration
• Tasks integration
• Random events
• Community skins

FAQ

Is this a medical app?

No. Regen uses fictional game indicators and does not provide medical advice.

Does Health measure my real health?

No. Health is a game value based on configured routines and work rhythm.

Can Regen stop me from working?

No. Regen never blocks work. It only suggests recovery.

Does Regen need internet?

No. The plugin is designed to run locally.