fatsecret-food

What fatsecret-food does

The plugin exposes three tools. analyze_food_photo identifies food using FatSecret Image Recognition and writes nothing. search_food searches by name for corrections or manual entry and also writes nothing. log_food_entry writes the confirmed entry to the diary and is the only tool that writes. A FATSECRET_RECOGNITION_BACKEND setting switches between the FatSecret Image Recognition API and the Hermes model's own vision plus text search, which needs no add-on.

Authentication uses one client ID and secret in two ways: OAuth 2.0 client credentials for image recognition and food search, and OAuth 1.0 signed requests with a profile token for diary writes. A one-time setup_auth.py opens fatsecret.com in the browser, asks you to allow access, and prints the two token variables to store in your shell profile or Hermes .env. Region and language are passed per call and default to US and en. Photos are downscaled with Pillow, and the tests run offline against recorded fixtures.

Key features

• Photo-based food identification through FatSecret Image Recognition
• Optional backend that uses the Hermes model's vision plus FatSecret text search
• Name search for corrections and manual entry
• Diary write limited to a single log_food_entry tool
• One-time OAuth setup script
• Offline tests with recorded fixtures

When to use it

• Photographing a meal and having Hermes log it to a FatSecret diary
• Correcting a misidentified food by searching its name
• Running without the paid recognition add-on by using the Hermes vision backend

Who it is for: Hermes Agent users who already track calories in FatSecret and want to log meals by sending photos.

How it fits with Hermes Agent

Built as a Hermes plugin that adds three tools and is placed in the Hermes agent plugins folder.

How to install fatsecret-food

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

ln -s "$(pwd)" ~/.hermes/hermes-agent/plugins/fatsecret-food
pip install requests requests-oauthlib Pillow

Requirements: A FatSecret platform app with client ID and secret, an OAuth token and token secret from setup_auth.py, the Image Recognition add-on unless the hermes backend is used, and requests, requests-oauthlib and Pillow

Note: The default image recognition backend needs a FatSecret Image Recognition add-on (Premier or Premier Free tier, with a 14-day trial).

FAQ