Skip to content

Home

Jump to bottom
Wei Liu edited this page Apr 22, 2026 · 1 revision

HiMe User Guide

Welcome! You've finished ./setup.sh and the dashboard is running at http://localhost:5173. This page walks you through the iOS app, the web dashboard, and the questions new users typically hit.

Contents

  1. Prerequisites check
  2. Setting up the iOS app
  3. Using the iOS app day-to-day
  4. The web dashboard
  5. FAQ
  6. Getting help

Prerequisites check

Before opening the iOS app, confirm the server is healthy:

Service URL Expected
Dashboard http://localhost:5173 HiMe dashboard loads
Backend API http://localhost:8000/health {"status":"ok"}
Watch exporter http://localhost:8765/ping pong

If any of these fail, run ./hime.sh logs. The most common cause is Docker still starting — wait 30–60 seconds and refresh.

1. Setting up the iOS app

Install

Either install HiMe from the App Store, or build from source with Xcode 16+ (see docs/INSTALL.md).

First-launch walkthrough

Five screens, in order:

  1. Welcome — "Say Hi to Healthy Me." Brief intro.

  2. Apple Health access — grant permission to read heart rate, sleep, steps, SpO₂, HRV, etc. HiMe only reads; it never writes to Apple Health.

  3. Server address — where your backend lives. Enter a bare host, no scheme or port:

    • localhost — iPhone Simulator on the same Mac as the server.
    • Mac's LAN IP (e.g. 192.168.1.100) — iPhone on the same Wi-Fi. setup.sh prints this at the end; or run ipconfig getifaddr en0 on the server Mac.
    • homelab.local — if your LAN publishes mDNS/Bonjour.
    • A public domain (e.g. example.com) — requires reverse-proxy with api. and watch. subdomains. See docs/DEPLOYMENT.md.

    Tap Test Connection to verify.

  4. AI data-sharing consent — HiMe sends your data to whichever LLM provider you chose in setup.sh (OpenAI / Anthropic / Gemini / …). Check the box to proceed; revocable anytime in Settings.

  5. Meet HiMeow — the pixel-art cat mascot. Long-press it for a quick health check-in.

Tap Start.

Auth token (public deployments only)

If you set API_AUTH_TOKEN in .env, paste the same value into Settings → Auth Token on the iPhone. For local LAN use, leave empty.

2. Using the iOS app day-to-day

Three tabs at the bottom; the middle one (Cat's Room) is default.

Tab 1 — Cat's Room (HiMeow)

A full-screen pixel-art room with a mood-shifting cat. The cat's face reflects your recent health state: happy, tired, stressed, relaxed, focused…

A status badge above the cat names the mood. A status message below summarises what's going on ("Your sleep is trending up — keep it consistent."). A control panel at the bottom holds Chat, Sync toggle, and Agent toggle.

Action Result
Tap the cat Random animation (jump / spin / tail wag).
Long-press the cat (0.6s+) Quick analysis — agent reads recent data and replies immediately.
Tap Chat Opens Telegram or Feishu to talk to the bot.
Toggle Sync Pause/resume sending health data to the server.
Toggle Agent Start/stop the backend agent (same as in the web dashboard).

Tab 0 — Dashboard (left)

Three sub-tabs:

Overview

  • Agent status card — active LLM, current state (Idle / Thinking / Executing), cycle count, token usage.
  • Health summary grid — cards grouped by category (Cardio, Activity, Sleep…). Each card shows latest value + trend arrow. Tap to expand into a chart. Sleep cards show a stacked bar of deep / core / REM / awake per night.

Reports

  • Agent-generated reports, newest first. Coloured alert badge (green info / orange warning / red critical). Tap to read the full markdown report.

Tasks

  • Scheduled tasks — cron + goal (e.g. 0 8 * * * → "Analyse my sleep"). Pause / Run Now / Delete.
  • Event triggers — rules like "if heart rate > 100 for 5 minutes, analyse cardiovascular stress." Configure feature, threshold, window, cooldown, goal.

Tab 2 — Collected Data (right)

Debug view. Every HealthKit sample the app has seen, grouped by metric. Shows count, latest timestamp, and upload status (green ✓ / orange pending). Useful when data looks missing — if a metric isn't listed here, the app didn't receive it from Apple Health.

Settings (gear icon)

  • Server — host, auth token, connection status, manual connect/disconnect.
  • Data & privacy — consent status, review/revoke.
  • Onboarding — replay the walkthrough.
  • HealthKit — authorization status, last sync time, Burst Mode (frequent syncs — battery-heavy, test-only), Force Fetch All Data Now.
  • Activity log — recent events; copy/clear.
  • About — version + build.

Widgets

Three iPhone widgets (home screen and/or lock screen):

  • Himeow Mood (small / medium) — cat emoji + mood label + latest message.
  • Vitals Grid (small / medium / large) — up to 8 metric cards (Heart, Steps, Sleep, SpO₂, HRV, Energy…).
  • AI Insight (medium / large) — latest report title + preview, coloured by alert level.

Apple Watch companion

When paired: cat head + mood label + AI message, a 2×2 grid of live metrics (Heart Rate, Steps, SpO₂, Sleep), a secondary row with HRV + Energy, and a footer showing sync status. Read-only — no starting the agent or editing rules on the watch.

3. The web dashboard (http://localhost:5173)

Seven pages in the left sidebar. Footer shows agent + stream status (green pulse = running). A language switcher at the top toggles English ↔ 中文.

Dashboard (/)

Real-time view of the raw health data flowing in. Four stat cards, a time-window selector (1 Hour / 1 Day / 1 Week / 1 Month), and interactive charts grouped by category. Auto-refreshes as data streams in. Check this first to confirm HealthKit data is arriving.

Agent Monitor (/agent)

Where you start the agent for the first time.

  • Status section — running indicator, uptime, task count, queue size, current state.
  • LLM provider + model dropdowns (pre-filled from .env); switch on the fly.
  • Big Start / Stop Agent button. First start takes 10–30 seconds.
  • Scheduled Tasks + Trigger Rules editors (same data as the iOS Tasks tab).
  • Activity log — live stream of agent events colour-coded by kind: system (blue), analysis (green), chat (purple), errors (red). You see thoughts, tool calls (SQL, code), and results in real time.

Analysis Reports (/reports)

Archive of everything the agent has produced. Search + alert-level filter + sort. Report cards show title, alert badge, timestamps, and a preview. Click to read the full markdown.

Prompt Manager (/prompts)

Three editable layers that shape agent behaviour:

  • Soul (Agent Editable) — core identity and goals. The agent may rewrite this as it learns; your edits might be overwritten.
  • Experience (Agent Editable) — learned patterns the agent writes to itself.
  • User (User Only) — immutable system instructions. Use for rules you never want the agent to touch.

Changes take effect on the next agent cycle — no restart needed. ⌘S to save.

Skills (/skills)

Reusable analysis playbooks. Each skill is a markdown file with a name (lowercase, alphanumeric, hyphens/underscores), a one-line description, and a body of step-by-step instructions.

  • Tick a skill → visible to the agent.
  • Untick → hidden (file preserved).
  • Delete → removed from disk.
  • Five bundled: baseline_change_point, circadian_alignment, respiratory_screen, sedentary_behavior_audit, sleep_regularity_index.

Memory & Tools (/knowledge)

Memory tab — SQLite tables the agent uses to store learned information. Read-only from the UI; the agent owns them.

Tools tab — tools the agent can invoke (sql, code, reports, replies, etc.) with descriptions and parameters. Reference.

Personalised Pages (/pages)

Custom HTML dashboards the agent generates on demand. Ask the bot in chat: "Create a page showing my weekly sleep trends" — a new page appears here. Click to view embedded, or open in a new tab. You cannot create pages by hand from this UI; ask the agent.

4. FAQ

Connection & setup

Q: The dashboard loads but shows "Disconnected" everywhere. The backend may still be starting. Wait 30s and refresh. If it persists, run ./hime.sh logs and look for missing API keys or port conflicts.

Q: iOS app says "Cannot connect to server."

  1. Both devices on the same Wi-Fi?
  2. From another LAN device: curl http://<mac-ip>:8765/ping should return pong.
  3. macOS firewall: System Settings → Network → Firewall → allow incoming for Docker / your Python process.
  4. Using a public domain? Verify DNS and HTTPS termination per docs/DEPLOYMENT.md.

Q: 401 Unauthorized from the iOS app. API_AUTH_TOKEN mismatch. Paste the same value into iOS Settings → Auth Token.

Q: Telegram bot is silent.

Q: Feishu card buttons do nothing. The Feishu card callback URL isn't set. It needs a public URL (tunnel or deployment). See docs/DEPLOYMENT.md → Feishu section.

Agent behaviour

Q: I started the agent but nothing happens. The agent is idle until it has work. It acts on:

  • Chat messages (Telegram/Feishu)
  • Scheduled tasks (cron)
  • Event triggers (rules)
  • Quick analysis (long-press the cat)

If none are configured, add a scheduled task or long-press the cat to test.

Q: The agent says things that don't match my data. Open the Activity Log in Agent Monitor and look at the tool calls. If its SQL query returned empty, the issue is ingestion, not the agent. Check the Dashboard page to confirm data is actually there.

Q: Can I change the LLM mid-conversation? Yes. Agent Monitor → change provider/model → effective next cycle. No restart.

Q: Agent uses too many tokens. Lower AGENT_MAX_TOKENS, reduce AGENT_CONTEXT_WINDOW_SIZE, or switch to a smaller model. For GPT-5 family, set OPENAI_REASONING_EFFORT=low (default medium is overkill for HiMe's tool loops).

Q: The agent overwrote my Soul prompt. Soul is Agent Editable — the agent rewrites as it learns. Put fixed instructions in the User prompt (User Only, locked), or move them into a Skill.

Q: How does fact verification work? Before sending any reply, HiMe runs a second LLM pass (FactVerifier) that cross-checks the reply against the tool results it was based on. If claims don't match the evidence, the reply is blocked. Configure with FACT_VERIFY_LLM_PROVIDER / FACT_VERIFY_LLM_MODEL (defaults to the main agent's provider).

Data & privacy

Q: Where is my health data stored? On the machine running the backend, in data/ (SQLite). Nothing leaves that machine except LLM calls to the provider you configured.

Q: How long is data kept? Rolling window of DATA_RETENTION_DAYS (default 30). A daily loop prunes older samples.

Q: How do I wipe everything? ./hime.sh reset — wipes data/, memory/, logs/. Confirms first. .env is preserved.

Q: Can I revoke AI consent? iOS → Settings → Data & Privacy → Revoke Consent. The app stops sending data immediately. Data already on the server stays until you reset.

Q: Is my data used to train the LLM? Depends on your provider's terms. HiMe never sends telemetry anywhere of its own — there is no HiMe-operated server.

iOS specifics

Q: HealthKit metrics are empty.

  1. iOS Settings → Health → Data Access → HiMe → enable read permissions.
  2. HiMe Settings → HealthKit → Force Fetch All Data Now.
  3. Has your Apple Watch actually been writing data? Wear it for a few hours.

Q: Widget isn't updating. Force-quit HiMe, tap the widget, wait a few seconds. If still stuck, remove and re-add the widget.

Q: Apple Watch app has no data. The iPhone must be reachable. The watch queues samples and syncs when the phone returns (green dot = connected, orange = queued).

Q: Cat mood never changes. Agent hasn't run yet, or recent data hasn't shifted. Long-press the cat to force a quick analysis.

Q: Can I delete the iOS app without losing data? Yes. Data lives on the backend. Reinstall, re-enter server URL, done.

Server management

Q: How do I update HiMe?

git pull
./hime.sh restart --rebuild   # docker mode
./hime.sh restart --clean     # native mode
.env, data/, memory/ are preserved. If new env vars appeared, diff .env.example against .env.

Q: How do I see what's happening inside?
./hime.sh logs tails logs/backend.log. Agent Monitor's Activity Log is the high-level view; backend.log is low-level.

Q: Can I run HiMe on a NAS / VPS / remote host?
Yes. Set API_AUTH_TOKEN, add your origin to CORS_ORIGINS, reverse-proxy behind HTTPS, and point the iOS app at your domain. See docs/DEPLOYMENT.md.

Q: Can I run multiple users on one backend?
Not officially in v1.0.0 — HiMe is designed for personal, single-tenant use.

---
5. Getting help

- Bug reports: open an issue at github.com/thinkwee/HiMe/issues.
- Discussions: GitHub Discussions (if enabled).
- Security issues: follow SECURITY.md — do not open a public issue.
- For contributors: AGENTS.md and docs/DEVELOPMENT.md.
- Deep install / deployment: docs/INSTALL.md, docs/DEPLOYMENT.md.

---
HiMe is research-grade software for personal use. It is not a medical device and does not provide diagnoses.

---

Clone this wiki locally