YouOS — Personal Email Copilot
YouOS is a full local Python app (not an instruction-only snippet). It drafts email replies in your style, grounded in your real past replies.
Naming: YouOS is the shared app/package. During setup it personalizes its name to OS (e.g. BaherOS) for your local instance at YOUOS_DATA_DIR=~/YouOS-Instances/<you>/ — that's a local config/data directory, not a fork of the project.
Safety & impact
Read these before installing:
- Sensitive data ingested locally. YouOS reads your Gmail (sent + threads), Google Docs, and optional WhatsApp exports into a local SQLite DB. This stays on your machine, but it is sensitive content — protect the data directory (
YOUOS_DATA_DIR/var/youos.db) accordingly.
- Installation runs local package code.
./scripts/install.sh builds a .venv and installs this repository — review the source (especially scripts/install.sh, pyproject.toml, app/) before running.
- Background persistence is opt-in. YouOS only runs as a launchd LaunchAgent if you explicitly run
youos service install. Foreground youos serve does not persist.
- Scheduled/nightly runs are opt-in. Ingestion, fine-tuning, and autoresearch only run automatically if you've enabled the nightly pipeline;
youos improve is the manual equivalent.
- External model fallback is optional. Drafting is on-device by default. Cloud fallback only fires if
review.draft_model or model.fallback is set to a cloud model — set model.fallback: none and review.draft_model: local for strict local-only operation.
Install and runtime model
- Install is manual: run
./scripts/install.sh (Python 3.11+) — it creates a .venv, installs YouOS, sets up the on-device model (MLX) on Apple Silicon, and runs the doctor
- Note: this executes local package install code from this repository; review source before installing
- Requires
python3 (3.11+) and a Google ingestion backend — gog (default), gws, or native (see Credentials)
- Drafts run on your fine-tuned local model by default (Qwen + your LoRA, served warm); the cloud is only a cold-start before your model is trained, or a fallback
- Optional runtime path override:
YOUOS_DATA_DIR
Credentials and configuration
- Required: a Google ingestion backend for Gmail/Docs —
gog (default), gws, or native (youos[google] + OAuth); set ingestion.google_backend
- Optional: Claude CLI/API credentials only for the cold-start/fallback (
review.draft_model / model.fallback)
- For strict local-only: set
review.draft_model: local and model.fallback: none
Trigger phrases
- "draft a reply to this email"
- "write this email for me"
- "how would I respond to this"
- "what would I say to"
- "help me reply"
- "draft in my style"
- "youos"
- "my email copilot"
- "email copilot"
- "my copilot"
- "generate a draft"
- "reply draft" / "email draft" / "draft reply"
- "compose reply"
- "write a response"
- "email response"
- "how do I usually reply to"
- "reply to this"
- "help me write"
- "write an email"
- "compose a response"
- "email assistant"
- "my writing style"
- "train on my emails"
Requirements
- Apple Silicon Mac (M1/M2/M3/M4) with 8GB+ RAM (16GB recommended) — the local model runs on MLX (
./scripts/install.sh sets it up)
- Python 3.11+
- A Google ingestion backend for Gmail/Docs: gog CLI (default), Google's
gws CLI, or the native Google API (youos[google] + OAuth)
- ~5GB free disk space
- Run the UI locally by default (do not expose publicly unless intentionally secured)
Quick start
# Install (creates .venv, installs YouOS + MLX on Apple Silicon, runs the doctor)
cd youos
./scripts/install.sh
source .venv/bin/activate
# Check system requirements (Python, Google backend, MLX, disk space, etc.)
youos doctor
# Run setup wizard (identity, ingestion, style analysis) — or open /welcome in the browser
youos setup
# Draft a reply (uses your local fine-tuned model by default)
youos draft "paste inbound email here"
youos draft --sender john@company.com "email text"
# Run the web UI (then open /feedback, /stats, /settings, /about)
youos serve
youos service install # or run it as a background service (starts at login)
# Compare the backends on YOUR mail, ranked by how closely each sounds like you
youos compare-models --limit 30 --semantic
# Warm local-model server (loaded once for fast drafting)
youos model server status
# Check status / view stats
youos status
youos stats
# Run the nightly pipeline manually (add --verbose for step-by-step output)
youos improve --verbose
# Golden benchmark (10 curated cases)
youos eval --golden
# Full corpus health report (pairs, quality scores, top senders)
youos corpus
# Ingest a WhatsApp chat export (optional — augments your corpus)
youos ingest --whatsapp ~/Downloads/WhatsApp-Chat.txt
# Add a sender note (immediately rebuilds their profile)
youos note john@company.com "integration partner, prefers bullet points"
# Submit a feedback pair directly from the terminal
youos feedback --inbound "email text" --reply "your reply" --rating 4
# Teardown (remove all data, keep code)
youos teardown
Drafting inside Gmail
Install the YouOS browser extension (Chrome/Edge/Brave) — it lives in the repo's
extension/ folder (homepage),
and the web UI's Gmail page has one-click "Load unpacked" steps. The extension adds a
panel to Gmail:
- Open an email → click the teal ✉ launcher → the panel opens
- Sender + message auto-detected; add an instruction or pick a tone
- Click Generate → drafted in your voice; Insert into Gmail drops it in the reply box
- Rate 1–5 and Submit feedback — YouOS learns from it, same as the Review Queue
A bookmarklet remains as a no-install fallback (it can break when Gmail changes its markup;
the extension doesn't).
How it works
- Ingests Gmail, Google Docs, WhatsApp exports — plus organic pairs from emails you sent without YouOS
- Builds a retrieval index — BM25 + query expansion + semantic (LRU-cached) + multi-intent + per-account isolation + same-thread 2× + subject + topic signals + sender-type boosts + quality scores + relative confidence thresholds
- When you ask for a draft: detects multi-intent, retrieves score-ranked thread-deduplicated exemplars (reply preserved 600 chars, inbound trimmed 400), prompt token budget enforced; generates with per-mode persona + first-name greeting on your fine-tuned local model by default (Qwen + your LoRA, served warm via
mlx_lm.server so it's fast and on-device). The cloud is only a cold-start (before your model is trained) or a fallback; a per-draft model badge + the Stats "Drafting with" row always show which model actually ran
- Every email you review trains the model further — curriculum-ordered, quality-filtered, training pairs deduplicated by similarity, DPO pairs supported; nightly pipeline skips steps when data insufficient
- Nightly: ingests + organic pairs, incremental persona re-analysis (90-day weighted, EWMA avg words, p25/p75 confidence intervals), fine-tunes (with golden eval check), runs autoresearch on rotating benchmark sample
- Autoresearch benchmarks rotate weekly (seeded re-sample) — prevents overfitting to fixed test cases; golden eval composite tracked in pipeline log
- Style drift detection: Stats dashboard flags when your writing patterns shift significantly
- Your best-rated, least-edited replies surface higher in future retrievals via quality scoring
- Sender profiles track reply-time patterns and topics;
youos note immediately rebuilds that contact's profile
- Submit feedback from terminal:
youos feedback --inbound "..." --reply "..." --rating 4
- Setup wizard asks for internal domains — accurate sender classification from day one
- Facts store (
/api/facts) — save context about contacts, projects, and preferences; facts are injected into generation prompts automatically for context-aware drafts
- Auto fact extraction — sender notes and feedback notes are parsed automatically on save using 15+ rule patterns (preferences, timezone, schedule, sign-offs, roles, relationships, project metadata); negation-aware with confidence scoring; LLM (Claude CLI) fallback for unstructured notes; fact deduplication/merging on upsert
- Measure it, don't guess —
youos compare-models drafts your held-out replies under each backend and scores them against what you actually wrote (voice-match), so you can verify the local fine-tuned model beats the cloud on your mail
- Readiness gate — a soft "preparing your voice model" banner holds you back from relying on drafts until your model is trained and benchmarked (with a "Run benchmark now" action); drafting still works meanwhile
- Becomes your OS — during setup the app personalizes its name from your first name (e.g. Baher → BaherOS)
Security & privacy notes
- Gmail/Docs ingestion uses your configured Google backend's auth (
gog / gws / native OAuth); review connected accounts before ingestion
- Drafting is on-device by default; the cloud is only the cold-start/fallback. If it's used (
review.draft_model: claude or model.fallback: claude), inbound email/context is sent to Claude for that draft
- For strict local-only operation, set
review.draft_model: local and model.fallback: none in youos_config.yaml
- Data location defaults to local instance paths under
YOUOS_DATA_DIR (e.g. ~/YouOS-Instances/<you>/), or the repo's var/
- Review
PRIVACY.md before first ingestion/deployment
Provenance
1---2name: youos3description: >4 YouOS — local-first personal email copilot that learns your writing style from Gmail,5 Google Docs, and WhatsApp exports, then drafts replies in your voice. Use for drafting6 replies, reviewing how you usually respond, and running a self-improving personal7 communication workflow.8metadata:9 source: https://skillmd.com/skills/lord1egypt/youos10 openclaw:11 requires:12 bins: ["python3", "gog"]13 platform: darwin14 arch: arm6415 minRam: "8GB"16 install:17 - kind: instructions18 label: "Manual install required"19 steps:20 - "./scripts/install.sh"21 - "source .venv/bin/activate"22 - "youos setup"23 credentials:24 required:25 - "A Google ingestion backend for Gmail/Docs (set ingestion.google_backend): gog CLI authenticated (default), Google's gws CLI authenticated, or the native Google-API backend (pip install youos[google] + OAuth)"26 optional:27 - "Claude CLI/API credentials only if model.fallback uses external provider"28 privacy:29 localStorage:30 - "SQLite DB under YOUOS_DATA_DIR/var/youos.db (or local var/youos.db)"31 networkEgress:32 - "None by default for local mode"33 - "Optional outbound requests when external fallback is enabled"34---3536# YouOS — Personal Email Copilot3738YouOS is a full local Python app (not an instruction-only snippet). It drafts email replies in your style, grounded in your real past replies.3940**Naming:** *YouOS* is the shared app/package. During setup it personalizes its name to *<First>OS* (e.g. **BaherOS**) for **your local instance** at `YOUOS_DATA_DIR=~/YouOS-Instances/<you>/` — that's a local config/data directory, not a fork of the project.4142## Safety & impact4344Read these before installing:4546- **Sensitive data ingested locally.** YouOS reads your Gmail (sent + threads), Google Docs, and optional WhatsApp exports into a local SQLite DB. This stays on your machine, but it *is* sensitive content — protect the data directory (`YOUOS_DATA_DIR/var/youos.db`) accordingly.47- **Installation runs local package code.** `./scripts/install.sh` builds a `.venv` and installs this repository — review the source (especially `scripts/install.sh`, `pyproject.toml`, `app/`) before running.48- **Background persistence is opt-in.** YouOS only runs as a launchd LaunchAgent if you explicitly run `youos service install`. Foreground `youos serve` does not persist.49- **Scheduled/nightly runs are opt-in.** Ingestion, fine-tuning, and autoresearch only run automatically if you've enabled the nightly pipeline; `youos improve` is the manual equivalent.50- **External model fallback is optional.** Drafting is on-device by default. Cloud fallback only fires if `review.draft_model` or `model.fallback` is set to a cloud model — set `model.fallback: none` and `review.draft_model: local` for strict local-only operation.5152## Install and runtime model5354- Install is **manual**: run `./scripts/install.sh` (Python 3.11+) — it creates a `.venv`, installs YouOS, sets up the on-device model (**MLX**) on Apple Silicon, and runs the doctor55- Note: this executes local package install code from this repository; review source before installing56- Requires `python3` (3.11+) and a Google ingestion backend — `gog` (default), `gws`, or native (see Credentials)57- Drafts run on your **fine-tuned local model by default** (Qwen + your LoRA, served warm); the cloud is only a cold-start before your model is trained, or a fallback58- Optional runtime path override: `YOUOS_DATA_DIR`5960## Credentials and configuration6162- Required: a Google ingestion backend for Gmail/Docs — `gog` (default), `gws`, or native (`youos[google]` + OAuth); set `ingestion.google_backend`63- Optional: Claude CLI/API credentials only for the cold-start/fallback (`review.draft_model` / `model.fallback`)64- For strict local-only: set `review.draft_model: local` and `model.fallback: none`6566## Trigger phrases6768- "draft a reply to this email"69- "write this email for me"70- "how would I respond to this"71- "what would I say to"72- "help me reply"73- "draft in my style"74- "youos"75- "my email copilot"76- "email copilot"77- "my copilot"78- "generate a draft"79- "reply draft" / "email draft" / "draft reply"80- "compose reply"81- "write a response"82- "email response"83- "how do I usually reply to"84- "reply to this"85- "help me write"86- "write an email"87- "compose a response"88- "email assistant"89- "my writing style"90- "train on my emails"9192## Requirements9394- Apple Silicon Mac (M1/M2/M3/M4) with 8GB+ RAM (16GB recommended) — the local model runs on MLX (`./scripts/install.sh` sets it up)95- Python 3.11+96- A Google ingestion backend for Gmail/Docs: [gog CLI](https://github.com/openclaw/gog) (default), Google's `gws` CLI, or the native Google API (`youos[google]` + OAuth)97- ~5GB free disk space98- Run the UI locally by default (do not expose publicly unless intentionally secured)99100## Quick start101102```bash103# Install (creates .venv, installs YouOS + MLX on Apple Silicon, runs the doctor)104cd youos105./scripts/install.sh106source .venv/bin/activate107108# Check system requirements (Python, Google backend, MLX, disk space, etc.)109youos doctor110111# Run setup wizard (identity, ingestion, style analysis) — or open /welcome in the browser112youos setup113114# Draft a reply (uses your local fine-tuned model by default)115youos draft "paste inbound email here"116youos draft --sender john@company.com "email text"117118# Run the web UI (then open /feedback, /stats, /settings, /about)119youos serve120youos service install # or run it as a background service (starts at login)121122# Compare the backends on YOUR mail, ranked by how closely each sounds like you123youos compare-models --limit 30 --semantic124125# Warm local-model server (loaded once for fast drafting)126youos model server status127128# Check status / view stats129youos status130youos stats131132# Run the nightly pipeline manually (add --verbose for step-by-step output)133youos improve --verbose134135# Golden benchmark (10 curated cases)136youos eval --golden137138# Full corpus health report (pairs, quality scores, top senders)139youos corpus140141# Ingest a WhatsApp chat export (optional — augments your corpus)142youos ingest --whatsapp ~/Downloads/WhatsApp-Chat.txt143144# Add a sender note (immediately rebuilds their profile)145youos note john@company.com "integration partner, prefers bullet points"146147# Submit a feedback pair directly from the terminal148youos feedback --inbound "email text" --reply "your reply" --rating 4149150# Teardown (remove all data, keep code)151youos teardown152```153154## Drafting inside Gmail155156Install the **YouOS browser extension** (Chrome/Edge/Brave) — it lives in the repo's157`extension/` folder ([homepage](https://github.com/DrBaher/youos/tree/main/extension)),158and the web UI's Gmail page has one-click "Load unpacked" steps. The extension adds a159panel to Gmail:160- Open an email → click the teal ✉ launcher → the panel opens161- Sender + message auto-detected; add an instruction or pick a tone162- Click **Generate** → drafted in your voice; **Insert into Gmail** drops it in the reply box163- Rate 1–5 and **Submit feedback** — YouOS learns from it, same as the Review Queue164165A bookmarklet remains as a no-install fallback (it can break when Gmail changes its markup;166the extension doesn't).167168## How it works1691701. Ingests Gmail, Google Docs, WhatsApp exports — plus organic pairs from emails you sent without YouOS1712. Builds a retrieval index — BM25 + query expansion + semantic (LRU-cached) + multi-intent + per-account isolation + same-thread 2× + subject + topic signals + sender-type boosts + quality scores + relative confidence thresholds1723. When you ask for a draft: detects multi-intent, retrieves score-ranked thread-deduplicated exemplars (reply preserved 600 chars, inbound trimmed 400), prompt token budget enforced; generates with per-mode persona + first-name greeting on your **fine-tuned local model by default** (Qwen + your LoRA, served warm via `mlx_lm.server` so it's fast and on-device). The cloud is only a cold-start (before your model is trained) or a fallback; a per-draft model badge + the Stats "Drafting with" row always show which model actually ran1734. Every email you review trains the model further — curriculum-ordered, quality-filtered, training pairs deduplicated by similarity, DPO pairs supported; nightly pipeline skips steps when data insufficient1745. Nightly: ingests + organic pairs, incremental persona re-analysis (90-day weighted, EWMA avg words, p25/p75 confidence intervals), fine-tunes (with golden eval check), runs autoresearch on rotating benchmark sample1756. Autoresearch benchmarks rotate weekly (seeded re-sample) — prevents overfitting to fixed test cases; golden eval composite tracked in pipeline log1767. Style drift detection: Stats dashboard flags when your writing patterns shift significantly1778. Your best-rated, least-edited replies surface higher in future retrievals via quality scoring1789. Sender profiles track reply-time patterns and topics; `youos note` immediately rebuilds that contact's profile17910. Submit feedback from terminal: `youos feedback --inbound "..." --reply "..." --rating 4`18011. Setup wizard asks for internal domains — accurate sender classification from day one18112. Facts store (`/api/facts`) — save context about contacts, projects, and preferences; facts are injected into generation prompts automatically for context-aware drafts18213. Auto fact extraction — sender notes and feedback notes are parsed automatically on save using 15+ rule patterns (preferences, timezone, schedule, sign-offs, roles, relationships, project metadata); negation-aware with confidence scoring; LLM (Claude CLI) fallback for unstructured notes; fact deduplication/merging on upsert18314. Measure it, don't guess — `youos compare-models` drafts your held-out replies under each backend and scores them against what you actually wrote (voice-match), so you can verify the local fine-tuned model beats the cloud on your mail18415. Readiness gate — a soft "preparing your voice model" banner holds you back from relying on drafts until your model is trained **and** benchmarked (with a "Run benchmark now" action); drafting still works meanwhile18516. Becomes *your* OS — during setup the app personalizes its name from your first name (e.g. Baher → BaherOS)186187## Security & privacy notes188189- Gmail/Docs ingestion uses your configured Google backend's auth (`gog` / `gws` / native OAuth); review connected accounts before ingestion190- Drafting is on-device by default; the cloud is only the cold-start/fallback. If it's used (`review.draft_model: claude` or `model.fallback: claude`), inbound email/context is sent to Claude for that draft191- For strict local-only operation, set `review.draft_model: local` and `model.fallback: none` in `youos_config.yaml`192- Data location defaults to local instance paths under `YOUOS_DATA_DIR` (e.g. `~/YouOS-Instances/<you>/`), or the repo's `var/`193- Review `PRIVACY.md` before first ingestion/deployment194195## Provenance196197- Source/homepage: https://github.com/DrBaher/youos198- This skill bundles a full local Python app and is intended for explicit local install/review before use.