Hermes Health Tracker

A Hermes skill for tracking meals, sleep, runs, workouts, injuries, and substances via natural language. Data is stored in Google Sheets. Meal nutrition is estimated using the USDA FoodData Central API.

You send messages like this to your Hermes agent (Telegram, CLI, etc.):

• "ate 2 chicken skewers and sticky rice for lunch"
• "slept 7 hours, woke up once, quality was ok"
• "ran 4 miles this morning, avg HR 143, cadence 174"
• "took 200mg ibuprofen for knee pain"

The skill parses your input, looks up nutrition data where relevant, and logs a row to the right tab in your Google Sheet.

What's inside

• Six tracked domains: meals, sleep, runs, workouts, injuries, substances
• USDA nutrition lookup with per-portion calorie and macro calculations
• A correction workflow that updates existing rows instead of creating duplicates
• Optional daily morning reminder that costs zero LLM credits

Prerequisites

Before installing, you'll need:

1. Hermes installed and running — See the Hermes install guide. This skill assumes the default install path (~/.hermes/).

2. gws CLI configured with Google OAuth — Hermes uses gws to talk to Google Sheets. You need to:

• Create a Google Cloud project and enable the Google Sheets API
• Create OAuth 2.0 credentials (Desktop app type)
• Authenticate gws with your Google account

For a walkthrough, see the Google Cloud OAuth documentation. Set the OAuth consent screen to "In production" (not "Testing") — Testing mode expires tokens every 7 days.

3. A USDA FoodData Central API key — Free. Sign up at api.data.gov/signup. Takes about 30 seconds.

Install

Clone the repo and run the installer:

git clone https://github.com/mikestarrdev/hermes-health-tracker.git
cd hermes-health-tracker
chmod +x setup.sh
./setup.sh

The installer will:

1. Check that gws and Hermes are available
2. Prompt for your USDA API key
3. Prompt for your timezone
4. Create a new Google Sheet named "Health Tracker" with all six tabs
5. Copy the skill to ~/.hermes/skills/health/
6. Write a config.sh with your Sheet ID, API key, and timezone
7. Ask whether you want to install the optional morning reminder
8. Restart the Hermes gateway

Once it finishes, message your Hermes agent something like ate 4 boiled eggs for breakfast to test.

Morning reminder

If you opt in during setup, a daily message will be sent to Telegram at 8am local time reminding you to log last night's sleep and any meals or workouts from the day before. It uses Hermes's no-agent mode, so the reminder itself doesn't consume any LLM credits.

Two things to know:

• The cron scheduler runs in UTC. The installer asks for the UTC hour corresponding to 8am in your timezone. You may need to adjust it twice a year when daylight saving changes.
• Telegram notifications must be enabled for your Hermes bot for the reminder to actually alert you.

Customizing the tracker

The Google Sheet is yours — you can add columns, rename tabs, or add new tabs. But if you change the schema, you'll also need to update SKILL.md so the Hermes agent knows how to write to the new format. The SKILL.md file describes each tab's columns to the model, and mismatches between the sheet and the skill will produce broken logs.

Sensible customizations:

• Add a mood or energy column to the sleep tab
• Add a new hydration tab
• Change the meal categories (default: breakfast, lunch, dinner, snack)
• Change the USDA search hints for foods common in your diet

Uninstall

rm -rf ~/.hermes/skills/health
hermes cron delete morning-health-reminder  # if installed

Your Google Sheet stays untouched — delete it manually if you want.

Contributing

Issues and PRs welcome. The skill was built and tested against gpt-5.4-mini on OpenRouter.

License

MIT