Covers Debian/Ubuntu, Fedora, Arch. Includes:
- Gemini CLI (recommended free: 1000 req/day, SSE direct)
- Claude Desktop (official Linux beta via apt, stdio)
- ChatGPT/Codex CLI (paid only, noted as unavailable on Linux)
- Built-in AI Coach (free API keys + Ollama offline)
- systemd service for auto-start
- venv vs system-wide install options
- No tzdata needed (Linux has system timezone DB)
Covers four AI integration paths:
- Gemini CLI (recommended free: 1000 req/day, SSE+stdio)
- Claude Desktop (free account, stdio only)
- ChatGPT Desktop (paid only, stdio)
- Built-in AI Coach (simplest: free API keys from OpenRouter/Groq/
Google AI Studio/Hugging Face/Ollama)
Includes full troubleshooting table for all known Windows issues.
The mcp SDK v2.0.0 (2026-07-28) renamed FastMCP to MCPServer
and removed the mcp.server.fastmcp import path entirely.
The standalone fastmcp package (PrefectHQ, v3.x) is the actively
maintained framework with identical @mcp.tool() decorator API.
- pyproject.toml: [mcp] extra now requires fastmcp>=3.0.0
- server.py: import changed from mcp.server.fastmcp to fastmcp
- mcp_stdio.py: unchanged (imports from diligence.mcp.server)
MCP SDK v2.0.0 extracted FastMCP into a separate package,
breaking the import at mcp.server.fastmcp.FastMCP. Pin to
v1.x until the server code is updated for the v2 API.
Claude Desktop's config file only supports stdio transport.
This script launches the MCP server in stdio mode, connecting
to the already-running Diligence backend at localhost:8000.
On Windows, Python's zoneinfo module has no system timezone database.
Without the tzdata package, ZoneInfo('UTC') raises ZoneInfoNotFoundError,
crashing both /api/points/today and /api/nutrition/today (Home and Keto
pages show 'failed to load').
Two fixes:
1. Add tzdata>=2024.1 to pyproject.toml dependencies so pip install
pulls it automatically
2. Harden dates.py with _safe_tz() that falls back to datetime.timezone.utc
(always available, no tzdata needed) as the ultimate fallback
Existing databases (from pre-July-5 installs) were missing:
- users.timezone (v4.2)
- nutrition_goals.diet_style and timezone_str (v4.3)
create_all only adds these to brand-new databases. The migration
system now detects and adds them on startup, matching the pattern
used for all other schema additions.
Built with Node 22 / Vite. Includes DW brand theme, ChatCoach,
category-grouped integrations, AgentConnect with all providers,
Dashboard checklist, Settings help section, gear icon.
AgentConnect.jsx rewritten:
- Option 1: Built-in AI Coach — lists all 8 providers with free tier
badges and 'Get key' links, step-by-step setup instructions
- Option 2: External AI Agent (MCP) — Claude Desktop (with Windows
path), Claude Code CLI, Cursor, Windsurf/other
- Page renamed from 'Connect Your AI Agent' to 'Connect AI'
Settings.jsx:
- Added Help & Support section: Report a Bug (GitHub Issues),
Ask a Question (GitHub Discussions), Star on GitHub
React hooks must be called unconditionally on every render. The
checklist useState was at line 89, after 'if (loading) return' at
line 70 — hooks violation crashed the entire React app (blank screen).
Moved to line 38 with the other state declarations.
Timezone:
- Add diligence/utils/dates.py with today_for_user(), now_for_user(), day_start_utc()
- Replace all 20 date.today() calls across 10 files with timezone-aware helpers
- Remove hardcoded Asia/Bangkok offset hack in nutrition router
- Change defaults from Asia/Bangkok to UTC in user model, nutrition model, config
- Add timezone field to RegisterRequest schema
- Set user.timezone from browser detection during registration
- Frontend sends Intl.DateTimeFormat().resolvedOptions().timeZone on register
Branding:
- Login page: Fitness Rewards -> Diligence, updated tagline and emoji
- index.html title: Fitness Rewards -> Diligence
Frontend rebuild:
- Fresh Vite build with all changes (index-CsKoBN0D.js)
- Nav bar, timezone detection, and branding all verified in built bundle
- New AgentConnect.jsx page with MCP URL, token, setup instructions
- Claude Desktop config snippet with copy button
- Claude Code CLI command with copy button
- Agent capabilities overview
- Added to bottom nav bar (6th item, plug icon)
- Backend /api/agent/config endpoint returns deployment-aware MCP details
- Nav padding adjusted for 6 items
- Frontend rebuilt with new page
Bug: API_TOKEN replacement ran before .env existed, and before the
existence check. On a clean clone the script errored immediately.
Fixed flow: banner → existence check → generate SECRET_KEY →
generate API_TOKEN → copy .env.example → replace both keys.
Also adds MCP connection info to output (matching setup.sh).
Root cause: ai_provider.py assumed a single JSON blob in an
'encrypted_value' column, but IntegrationConfig stores each credential
as a separate row with config_key + config_value columns.
Fixes:
- Query groups rows by provider, decrypts each config_value separately
- Correct decrypt_value(secret_key, ciphertext) argument order
- Filter by user_id so providers are per-user
- Callers (ai_chat.py, chat()) now pass user_id through
SEC-11 removed algorithm from Settings but missed 3 call sites:
- auth.py line 68: jwt.decode in get_current_user
- integrations.py lines 58, 120: jwt.decode in OAuth callbacks
All now use ALGORITHM constant or inline 'HS256'.
The SEC-06 replacement swallowed the trailing comma into the comment:
allow_credentials=False # comment, ← comma in comment
Fixed to:
allow_credentials=False, # comment ← comma after value
Previous commit wiped App.jsx due to emoji encoding error in the
patch script. Restored from Stream A commit (c075eb9), then applied
ChatCoach changes using a file-based Python script to handle unicode.
- import ChatCoach from './pages/ChatCoach' (line 21)
- NavLink /chat with brain emoji + 'Coach' label (line 95)
- Route /chat -> ProtectedRoute -> ChatCoach (line 125)
WHOOP developer registration requires device ownership. Sync service
will be built against their documented API; first WHOOP-owning user
serves as the integration tester. Focus on Garmin and Oura first.
Frontend:
- ChatCoach.jsx: streaming chat UI with SSE, provider indicator, suggestion
chips, 'no AI configured' state with setup link
- App.jsx: import + /chat route + nav bar (More → Coach with brain emoji)
- api.js: getAIStatus() method
Documentation:
- README.md: 'Built-in AI Coach' section with 8-provider table, external
agent config snippets for Claude Desktop, Claude Code, Cursor, Windsurf,
and COROS multi-MCP pattern
- AGENT_GUIDE.md: multi-device integration, Strava AI/ML warning,
provider-agnostic statement
Nav bar: Home | Log | Keto | Programs | Coach
Settings still reachable at /settings (linked from Coach setup prompt)
Abstract base class for device sync services (device_sync_base.py):
- Standard OAuth token management with automatic refresh
- Credential decryption from integration_configs table
- Activity import pipeline with deduplication by external_id
- Webhook validation and handling interface
- get_valid_token(), get_credentials(), import_activity() helpers
Garmin, WHOOP, and Oura sync service implementations follow when
API credentials are obtained (Scot action items):
- Apply for Garmin Developer Program (DiligenceWorks Pte. Ltd.)
- Register WHOOP developer app at developer.whoop.com
- Register Oura app at cloud.ouraring.com
AI coaching service (backend/app/services/ai_provider.py):
- Two code paths: OpenAI-compatible (6 providers) + Anthropic (Claude)
- Streaming SSE responses via httpx async
- System prompt built from AGENT_GUIDE + live user context
- Graceful error handling for all provider failures
- Gemini adapter for Google's generateContent API
Chat endpoint (backend/app/routers/ai_chat.py):
- POST /api/ai/chat — SSE streaming response
- GET /api/ai/status — check configured provider
- History capped at 20 messages, content at 4K chars
Provider registry expanded to 20 providers:
- 9 device integrations (strava, polar, garmin, whoop, oura, coros, fitbit, withings, suunto)
- 8 AI providers (openai, openrouter, huggingface, groq, ollama, claude, gemini, custom_ai)
- 3 other (usda, nutritionix, telegram)
- Categorized: device, ai_provider, nutrition, notifications
- COROS: MCP bridge approach (no API integration needed)
- Strava: AI/ML warning per their ToS
Frontend ChatCoach.jsx to follow in next commit.
SEC-16: Add frontend ports mapping (80:80) to docker-compose.yml
UI-01: Add routes for Welcome, SettingsIntegrations, MealPlan in App.jsx
SEC-01: Remove traceback leak from auth error responses
SEC-02: Fix require_admin to use is_admin column (was undefined ADMIN_USERNAME)
SEC-03: Add API_TOKEN auth for MCP connector -> backend communication
SEC-04: OAuth state now uses signed JWT tokens (was raw user UUID)
OS-01: First registered user gets admin immediately during registration
10 files changed, 97 insertions(+), 25 deletions(-)
Meal plan now includes:
- Bilingual headers throughout (day names, meal labels, notes)
- Full recipes for all 11 meals inline with bilingual ingredient tables
- Thai translation of every cooking step
- Bilingual prep schedule and substitution rules
Shopping list already had bilingual item tables; added Thai to intro and cost sections.