# PROJECT.md — Hermes OS

Mobile-first dashboard for Hermes Agent. Visibility into state, control over behavior, and self-improvement — all from your phone.

## Architecture

```
Phone/Browser → Next.js (port 3100) → proxy routes → Hermes WebAPI (8643) + Gateway (8642)
```

All API calls proxy through Next.js server-side route handlers. No CORS, no cross-origin issues. The frontend makes same-origin requests only.

## Modules

### Pulse (/)
Home screen. Status card (model, online/offline), stats (sessions, tokens, platforms), memory usage bars, platform breakdown, quick links to Skills/Cron/Soul/Config, recent sessions list. Pull-to-refresh.

### Memory (/memory)
Agent + User memory tabs. View entries, inline edit, delete with confirm, add new. Usage bar with char limit. All mutations go through WebAPI.

### History (/history)
Session list with platform filter (All/CLI/Telegram/Discord/Web) and full-text search. New session creation (/history/new). Session replay with:
- Newest-first message order
- Verbosity toggle: Compact (text only) / Normal (+ tool calls) / Full (+ reasoning + expanded results)
- Message input to continue sessions
- Thinking indicator while agent runs
- Session delete with confirm
- Refresh button

### Skills (/skills)
Categorized skill browser with search/filter. Skill detail renders SKILL.md as proper markdown (headings, code blocks, tables, blockquotes). Shows linked files.

### Cron (/cron)
Job list grouped by status (active/paused/other). Manual trigger button. Detail page (/cron/[id]) with job metadata, prompt, and output history read from filesystem.

### Soul (/soul)
SOUL.md editor. Direct filesystem read/write. Save/revert with dirty detection.

### Config (/config)
Read-only config viewer. Model, terminal, memory, display sections.

## Stack

- Next.js 15, TypeScript, Tailwind CSS v4
- TanStack Query for server state
- Lucide icons, react-markdown + remark-gfm
- PWA manifest + service worker
- systemd user services for persistence

## Services

```bash
# Deploy (build + install services + restart)
bash deploy/deploy.sh 3100

# Manual control
systemctl --user status hermes-os
systemctl --user status hermes-webapi
systemctl --user restart hermes-os
```

## Environment

| Variable | Default | Description |
|---|---|---|
| `HERMES_BACKEND_URL` | `http://127.0.0.1:8643` | WebAPI (FastAPI) |
| `HERMES_GATEWAY_URL` | `http://127.0.0.1:8642` | Gateway (aiohttp, cron jobs) |
| `HERMES_SOUL_PATH` | `~/.hermes/SOUL.md` | Persona file |
| `HERMES_CRON_OUTPUT` | `~/.hermes/cron/output` | Cron output directory |