mail-notify 1.0.0__tar.gz

mail_notify-1.0.0/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+All notable changes to ccmail. Versions follow [Semantic Versioning](https://semver.org/).
+
+## 1.0.0 - 2026-10-13
+
+First stable release. What is stable is listed in [docs/STABILITY.md](docs/STABILITY.md).
+
+New: `mail-notify setup [--autostart]` installs the hooks, the skill and the short command in one step (`init`
+stays separate: it asks for the password).
+
+Fixed before release: `status` and `stop` no longer treat an answer from a foreign daemon (HTTP 401/403, for
+example another data folder's) as "our daemon is running"; the source distribution now ships the full test suite
+(`MANIFEST.in`).
+
+The distribution (PyPI/pipx) name is `mail-notify`, matching the command and the repository; the Python module and
+the daemon keep the name `ccmail`, and `ccmail` still works as a command.
+
+### Known limitations
+- macOS, Linux and mail providers other than Gmail (Outlook, iCloud and Yahoo presets) are covered by the
+  automated tests only; real-system testing is planned for a later release.
+- Hints in the terminal and in the web app now name the short `mail-notify` command (`python -m ccmail` still works).
+
+### Changed (summary)
+- The summary in `summary` mode now covers the whole answer in at most 10 short lines: a lead, one line per
+  section ("Heading: what it opens with") sampled evenly across the message, and the closing question. The default
+  `summary_chars` is 300. The scrollable box of the HTML mail holds the complete answer (in `full` mode, the part
+  that is not already shown above it).
+- `install-skill` and `install-hooks` also create the short `mail-notify` command, so there is no third step.
+- Summary lines are short (about 130 characters; one bullet per section; a table is named by its first column),
+  the default `summary_chars` is 300 (the outcome fits in 300 characters), and the box no longer repeats the sentences the answer starts with.
+- The scrollable box formats the Markdown of the answer: fenced code as a code block, inline code, bold, headings and
+  bullets, *italic*; bold may wrap inline code, and `full` mode formats the outcome too (everything escaped; the
+  plain-text part is unchanged).
+
+### Added (command name)
+- `mail-notify` is a command of its own (console script next to `ccmail`), and `install-cli` / `uninstall-cli` write
+  or remove a small launcher in a folder already on `PATH`, for setups where the Scripts folder is not (Microsoft
+  Store Python). The launcher only ever overwrites or deletes a file it wrote itself.
+
+### Added (language)
+- The web app is available in English: the `language` setting now covers the page, the mails and the command line.
+  `auto` follows Claude Code's own `language` setting (Italian/English), then the system language. Catalogs are
+  static files (`web/lang-en.js`, `web/lang-en-app.js`), applied without network access; a test checks that every
+  catalog entry still exists in the page.
+
+### Fixed
+- Several commands arriving in one pass (for example ON then OFF) are applied oldest first, so the project ends
+  in the state asked for last; before, the newest was applied first and the older one won.
+
+### Added
+- A verified reply that cannot be delivered (no chat tied to the mail, unknown or expired reference, delivery to
+  Claude switched off) is answered with a mail in the usual layout whose OUTCOME says "reply discarded" and why.
+  Capped at 5 an hour; ccmail's own mails are never answered, so no loop.
+- `html_mail` setting (off by default): mails carry an HTML alternative next to the unchanged plain text, with
+  quick-reply buttons (OFF / ON / PAUSE 60, and "Write to Claude") that are pre-filled `mailto:` replies, and the
+  whole message in a box with its own scroll bar. The box follows `content_mode` (nothing extra in `title`/`minimal`).
+  One-click actions without pressing Send are not possible with a loopback-only daemon (Gmail actions need
+  registration with Google and a public HTTPS endpoint).
+
+## 0.6.0
+
+### Added
+- **Cross-platform daemon**: data folders for Windows, macOS and Linux; credentials in Windows Credential Manager,
+  macOS Keychain or Linux Secret Service (password through stdin only), with an announced 0600-file fallback;
+  autostart through Task Scheduler, LaunchAgent or `systemd --user` (XDG autostart as last resort).
+- Provider presets (Gmail, Outlook/Microsoft 365, iCloud, Yahoo, custom) in `ccmail init` and the web app.
+- `language` setting (`auto`/`it`/`en`): mails, suggested commands, messages delivered to Claude and the command line.
+  `PAUSE` is accepted next to `PAUSA`.
+- `device_name` setting: a `Device:` line in mails when ccmail runs on several computers.
+- `ccmail doctor [--network]`: installation check that prints no secrets (credentials, hooks, interpreter, skill,
+  autostart, daemon, mail servers).
+- `ccmail install-skill` / `uninstall-skill`: the `mail-notify` skill ships inside the package.
+- `CLAUDE_CONFIG_DIR` is honoured for settings, skills, transcripts and the account name.
+- The daemon picks a free port when the configured one is taken by another program.
+- `docs/RESOURCES.md`: measured token, CPU, memory, disk, network and latency costs.
+- Combination tests (`tests/test_matrix.py`): every mail kind x content mode x language x reply options, and policy vs. dry run.
+- Community files, CI matrix (Windows/macOS/Linux x Python 3.10-3.13), release workflow with PyPI trusted publishing.
+
+### Fixed
+- The answer mail of an e-mail reply was still skipped as a "stop hook loop": the reply reaches the chat through a
+  Stop hook, so its turn ends with `stop_hook_active` set. The guard no longer applies to that one-shot turn.
+- The IMAP scan fetched one header per message each pass; it now asks for all of them in a single command.
+- The answer to a reply sent by e-mail was never mailed back when the turn was short or processes were still running
+  (the user, being away, never saw it). A turn started by an e-mail reply is now always mailed at its end, with the
+  subject "risposta alla tua email"; the per-project switch, snooze and hourly cap still apply.
+
+### Changed
+- Detached daemon start on POSIX uses a new session; `pythonw.exe` only on Windows.
+- The design notes moved from the README to `docs/HOW-IT-WORKS.md`; working notes to `docs/dev/`.
+
+## 0.5.0
+
+### Added
+- Reply-by-email control channel (`inbound_enabled`): `OFF` / `ON` / `PAUSA [min]` in the first line of a reply.
+- Optional delivery of free-text replies into the Claude chat (`inbound_to_claude`, off by default).
+- Mails are split into sections (outcome, background processes, suggested commands, management) and carry
+  `Chat: <name>`; account name comes from the Claude account.
+- Usage-limit reached is its own event; summaries never cut a sentence in the middle.
+- `ccmail diagnose` shows the reply channel state.
+
+### Fixed
+- Replies sent to oneself were rejected as unauthenticated: Gmail's Sent label is now used.
+- The test mail was not recorded, so the app kept saying "SMTP not yet verified".
+
+## 0.3.0
+
+### Added
+- Chat names: the daemon reads the Claude desktop app's per-chat metadata (title, project folder, archived flag, last activity, and the Claude Code session id). Mails show `Chat: <name>`; unknown chats show `Sessione: <8 characters>`.
+- Title fallback: when app metadata is missing, the title is the latest `custom-title` record at the end of the session transcript (read from the tail of the file only, cached).
+- Discovery of app metadata in both the Microsoft Store package location (`%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude`) and `%APPDATA%\Claude`, merged by session id. Override with `CCMAIL_CLAUDE_SESSIONS` (paths separated by `;`).
+- Stable project resolution: chat folder, then a chat whose folder matches the transcript folder, then `CLAUDE_PROJECT_DIR`, then the shortest working folder seen for that transcript folder. Sub-folders are never projects; sub-agent transcripts are excluded.
+- Startup repair: realigns stored sessions to their projects and removes projects with no sessions or chats; per-project switches are kept.
+- Activity API: `GET /v1/projects?chats=N` (default 5 newest non-archived chats per project, `0` = all; archived chats listed separately) and `GET /v1/diagnostics`.
+- `ccmail diagnose`: read-only report of what ccmail sees in the desktop app.
+- Per-project on/off switch (`PUT /v1/projects/enabled`). When off, no mail and no wake-ups for that project. `ccmail status --cwd <folder>` reports it.
+- Honest session states: working, waiting (only if recent), waiting for background processes, periodic check, quiet (idle over 6 h), ended, archived, stale, uncertain.
+- `PostToolBatch` hook (async) for liveness.
+
+### Changed
+- Projects are derived from the chat's folder instead of the current working folder.
+
+### Upgrade notes
+- Run `ccmail install-hooks` again and restart Claude Code (the new `PostToolBatch` hook).
+
+### Known limits
+- The desktop app's metadata format is internal and undocumented. Every read soft-fails: if the format changes, ccmail falls back to hook data.
+- A chat could in theory change its Claude Code session id after resume or compaction. Not observed so far.
+
+## 0.2.0
+
+### Added
+- Background-task awareness: while tasks run in the background (`Stop.background_tasks`), intermediate `Stop` events send no mail.
+- Periodic wake-up: every `heartbeat_minutes`, and only while tasks are still running, the daemon wakes Claude through an `asyncRewake` Stop hook (`ccmail wake`). Claude checks the tasks and its short reply is mailed as a status update. A `skill` mode is available where Claude schedules its own wake-ups.
+- "Finished" mail: one mail when the last background task disappears.
+- Watchdog rule: an optional silent-session watchdog (`watchdog_minutes`), which must be off or at least twice `heartbeat_minutes`.
+- Summary mode (`content_mode = summary`, default): a short extractive summary of the turn, capped by `summary_chars`.
+- Minimal mode (`content_mode = minimal`): no model-derived text at all.
+- Account name (`account_name`), shown in every mail as `Account:`; empty = Windows user name.
+
+## 0.1.0
+
+### Added
+- Local daemon for Windows that emails about Claude Code events through Gmail SMTP, with a local configuration web app on `127.0.0.1`.
+- Hooks (`Stop`, `Notification`, `StopFailure`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PostToolUse` for `Bash`) forwarded to the daemon; all decisions are made in the daemon.
+- Anti-spam gates: no confirmation mails, minimum turn length for `Stop`, mute after toggle, per-session cooldown, hourly cap, selectable `Notification` types, title-only mode.
+- Credentials in Windows Credential Manager, with a DPAPI-encrypted file fallback.
+- Commands: `init`, `on`, `off`, `status`, `test`, `open`, `stop`, `daemon`, `install-hooks`, `uninstall-hooks`, `migrate`.

mail_notify-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+Be respectful and constructive. Harassment, personal attacks and discrimination are not tolerated in issues, pull
+requests or discussions. Assume good faith, be specific, and keep feedback about the work.
+
+Maintainers may edit or remove contributions that break these rules and may restrict participation. Report problems
+privately through the repository's security advisory form or by contacting the maintainer on GitHub.
+
+This is a short statement in the spirit of the Contributor Covenant 2.1.

mail_notify-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Thanks for helping. ccmail is deliberately small: standard library only, no runtime dependencies. Please keep it so.
+
+## Setup
+
+```bash
+git clone https://github.com/lobascioemanuele-droid/mail-notify && cd mail-notify
+python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e .
+PYTHONPATH=src:tests python -W ignore -m unittest discover -s tests     # Windows: set PYTHONPATH=src;tests
+```
+
+`tests/test_matrix.py` runs every mail kind x content mode x language x reply option and compares the
+policy with the web app's dry run: extend its tables when you add a kind, a mode or a setting.
+
+Tests isolate the data folder (`CCMAIL_HOME`), the desktop-app metadata (`CCMAIL_CLAUDE_SESSIONS`) and the account
+name, and pin `CCMAIL_LANG=it`. They never touch your real credentials or `~/.claude`.
+
+## Rules
+
+- **Never** handle a real password in code, tests, logs or issues. Use fake values.
+- No personal paths, names or addresses in code, tests or docs.
+- Texts a user can see exist in Italian and English: write them as an `(it, en)` pair with `i18n.pick`.
+- Anything that can send mail, or can reach Claude, needs a test for the case where it must *not* happen.
+- Platform code goes through the small seams that already exist (`paths`, `credstore`, `autostart`) so it can be tested
+  on any OS.
+- Update `CHANGELOG.md`. Add docs when behaviour changes, and `docs/RESOURCES.md` when a change alters what ccmail
+  sends to the model, polls, or runs.
+
+## Security issues
+
+Report them privately: see [SECURITY.md](SECURITY.md).

mail_notify-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mail-notify contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mail_notify-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md CHANGELOG.md SECURITY.md CONTRIBUTING.md CODE_OF_CONDUCT.md
+recursive-include tests *.py
+recursive-include docs *.md
+global-exclude __pycache__ *.py[cod]

mail_notify-1.0.0/PKG-INFO

@@ -0,0 +1,388 @@
+Metadata-Version: 2.4
+Name: mail-notify
+Version: 1.0.0
+Summary: Local daemon that e-mails you about Claude Code events, with a local settings web app.
+Author: mail-notify contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lobascioemanuele-droid/mail-notify
+Project-URL: Source, https://github.com/lobascioemanuele-droid/mail-notify
+Project-URL: Issues, https://github.com/lobascioemanuele-droid/mail-notify/issues
+Project-URL: Changelog, https://github.com/lobascioemanuele-droid/mail-notify/blob/main/CHANGELOG.md
+Keywords: claude,claude-code,notifications,email,hooks,smtp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mail-notify
+
+**E-mail notifications for [Claude Code](https://code.claude.com), with a local settings web app.**
+A small daemon on your own computer mails you when Claude finishes a long task, needs a permission, hits an error or a
+usage limit, or when your background processes finish. You can answer from your phone by replying to the mail.
+
+*Naming: the package and the command are `mail-notify`; the daemon and the Python module inside are called `ccmail`
+(`ccmail` also works as a command).*
+
+[![CI](https://github.com/lobascioemanuele-droid/mail-notify/actions/workflows/ci.yml/badge.svg)](https://github.com/lobascioemanuele-droid/mail-notify/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+- **Few mails, on purpose.** Every mail passes several gates (turn length, cooldown, hourly cap, event types). Turning
+  it on or off sends nothing.
+- **Private by design.** Standard library only, no telemetry. The only thing that leaves your machine is the mail
+  itself, sent through your own mail account. The password lives in your system's credential store.
+- **Reply to act.** Reply `OFF`, `ON` or `PAUSE 60` to a notification or, if you enable it, write a sentence that is
+  delivered to the Claude chat that sent the mail.
+- **Understands your chats.** Mails name the project, the chat and your Claude account, and carry a short summary of
+  what Claude said (about 300 characters, at most 10 lines; the complete answer follows in a scrollable box).
+- **Works while you are away.** While background tasks run, Claude is woken at a period you choose, only when tasks
+  exist, to report their status.
+
+> **Tested today: Windows with Gmail.** macOS, Linux and mail providers other than Gmail (the Outlook, iCloud and
+> Yahoo presets) are implemented and covered by the automated tests in CI, but are **not yet tested on a real
+> system: that is planned for a later release.** Please report what you find.
+
+## Install step by step
+
+You need your mail account's app password and about fifteen minutes. Run every command in **your own terminal**.
+ccmail never asks Claude for your password.
+
+### Requirements
+
+- Python 3.10 or newer.
+- [Claude Code](https://code.claude.com), as the CLI or the desktop app.
+- A mail account that allows SMTP with an **app password**. Presets exist for Gmail, Outlook, iCloud and Yahoo, and
+  you can enter any SMTP server.
+- Optional, for replies by mail: IMAP access to the same mailbox.
+
+### Step 1: install the package
+
+Install with [pipx](https://pipx.pypa.io), which keeps the program in its own environment. Once mail-notify is on PyPI:
+
+```bash
+pipx install mail-notify
+```
+
+To install the current version from the repository instead:
+
+```bash
+pipx install git+https://github.com/lobascioemanuele-droid/mail-notify
+```
+
+With Microsoft Store Python the `mail-notify` command can be "not found", because its Scripts folder is not on
+`PATH`. In that case use `python -m ccmail` instead of `mail-notify` in every step below, or run
+`python -m ccmail install-cli` once: it creates a short `mail-notify` command in a folder that is already on `PATH`.
+
+### Step 2: set up the sender account
+
+```bash
+mail-notify init
+```
+
+The prompts ask for the sender address, the provider (the right app-password link is shown for it), the app password,
+the recipient (it defaults to the sender) and an optional device name. The app password is typed in a **hidden**
+prompt and stored only in the system credential store (Windows Credential Manager, macOS Keychain or Linux Secret
+Service). Never paste it into a chat, a file or an issue. This step sends no mail.
+
+Where to create an app password:
+
+- Gmail: https://myaccount.google.com/apppasswords (needs 2-step verification)
+- Outlook: https://account.live.com/proofs/AppPassword
+- iCloud: https://account.apple.com/account/manage
+- Yahoo: https://login.yahoo.com/account/security
+
+### Step 3: install the hooks, the skill and the short command
+
+```bash
+mail-notify setup --autostart
+```
+
+One command does all of this, and sends nothing:
+
+- adds ccmail's hooks to Claude Code's settings (a backup of the file is made first);
+- copies the `/mail-notify` skill to `~/.claude/skills/mail-notify/`;
+- creates the short `mail-notify` command if it is missing;
+- with `--autostart`, starts the background daemon at logon.
+
+It never asks for the password (that is `init`, step 2) and can be run again at any time. The three parts are also
+available one by one: `install-hooks`, `install-skill` and `install-cli`.
+
+### Step 4: restart Claude Code
+
+Close and reopen Claude Code: hooks and skills are read at startup. After that `/mail-notify` appears in the list of
+skills.
+
+### Step 5: turn it on and test it
+
+```bash
+mail-notify on
+```
+
+Notifications are **off** after installation, so nothing is sent until you run this. `on` sends no mail.
+
+```bash
+mail-notify test
+```
+
+This sends **one** test mail. It also works while notifications are off.
+
+```bash
+mail-notify open
+```
+
+This opens the settings web app in your browser. It listens on `127.0.0.1` only and uses a one-time sign-in link.
+Optionally, in its **Rules** tab, turn on:
+
+- **Control by replying to the e-mail** (reply `OFF` / `ON` / `PAUSE`; needs IMAP, see above).
+- **Replies reach Claude** (free-text replies are delivered to the chat that sent the mail).
+- **E-mail with buttons** (an HTML version with tappable quick-reply cards).
+
+### Step 6: use it
+
+In Claude Code, the `/mail-notify` skill accepts `on`, `off`, `status`, `test` and `open`:
+
+```bash
+/mail-notify on
+```
+
+```bash
+/mail-notify status
+```
+
+Each project also has its own switch in the web app's **Activity** tab.
+
+When reply control is on, each mail tells you how to reply. Write one of these on the **first line** of your reply:
+
+- `OFF`: turns notifications off for that project.
+- `ON`: turns them back on for that project.
+- `PAUSE 60` (or `SLEEP`, or `PAUSE` alone for 60 minutes): silence on all projects for that many minutes.
+
+### Updating
+
+Update the package (use the command that matches how you installed it):
+
+```bash
+pipx upgrade mail-notify
+```
+
+```bash
+pipx install --force git+https://github.com/lobascioemanuele-droid/mail-notify
+```
+
+Then refresh the hooks and the skill, and restart Claude Code:
+
+```bash
+mail-notify setup
+```
+
+### Uninstalling
+
+Stop the daemon, then remove the pieces in this order:
+
+```bash
+mail-notify stop
+```
+
+```bash
+mail-notify uninstall-hooks --autostart
+```
+
+```bash
+mail-notify uninstall-skill
+```
+
+```bash
+mail-notify uninstall-cli
+```
+
+```bash
+pipx uninstall mail-notify
+```
+
+Uninstalling does not delete the data folder or the stored password. Delete the data folder yourself (on Windows
+`%APPDATA%\ccmail`), remove the ccmail entry from your credential store (on Windows it is `ccmail:smtp` in Credential
+Manager), and revoke the app password at your mail provider.
+
+## What a mail looks like
+
+- **Header:** `Project:`, `Account:` and `Chat:` (the chat's name in the desktop app, or `Session:` with a short id when
+  the name is unknown). `Device:` appears when you set a device name. Turn duration and type follow for a finished turn.
+- **OUTCOME** (`ESITO` in Italian): a short summary of the whole answer, about 300 characters (the `summary_chars`
+  setting) and at most 10 lines: a lead, one line per section, and the closing question when the answer ends with one.
+  With HTML mail on, the complete answer is in a scrollable box below it.
+- **Background processes:** how many are still running, and their ids, when there are any.
+- **Suggested commands:** a numbered list tailored to the message, to paste into the chat. They are tappable boxes
+  when "Replies reach Claude" is on.
+- **Quick-reply cards** (HTML mail with reply control on): `OFF`, `ON` and `SLEEP` (a 1-hour pause on all projects),
+  other pauses (15 minutes, 3 hours, 8 hours) and, if "Replies reach Claude" is on, "Write to Claude". Each card opens
+  a pre-filled reply; you still press Send.
+- **Reply instructions** in plain text, when reply control is on.
+
+## What you get
+
+| Mail | When |
+|---|---|
+| Task finished | A turn longer than 2 minutes (setting) ended |
+| Needs your input | A permission prompt or a question is waiting |
+| Error / usage limit | An API error, or the account limit was reached (with the reset time) |
+| Background processes | Periodic status while they run; one mail when the last one ends |
+| Chat stalled | Optional watchdog: no events for N minutes with tasks declared |
+
+### HTML mail (optional)
+
+Turn on **E-mail with buttons** in the web app's Rules tab and every mail also carries an HTML version next to the
+unchanged plain text: a coloured header by event type, the data in a grid, quick-reply cards, the suggested commands
+as tappable boxes (when "Replies reach Claude" is on), and the whole message in a box with its own scroll bar (at most
+340 px tall). The same layout is used for the confirmation, "command executed" and "reply discarded" mails.
+
+- The cards are pre-filled replies (`mailto:`): you still press Send. One-click actions inside Gmail need registration
+  with Google and a public HTTPS endpoint, which a daemon listening on loopback cannot offer.
+- A mail app that does not show HTML shows the plain text, without cards or the scroll box.
+- Nothing extra leaves your machine: the box follows the content mode (`title` and `minimal` add nothing), and text
+  goes through the same secret redaction.
+- A verified reply that cannot be delivered (no chat tied to the mail, unknown or expired reference, delivery to
+  Claude switched off) is answered with a mail whose outcome says "reply discarded" and why. At most 5 an hour.
+
+### Settings web app
+
+`mail-notify open` shows: an **Overview** with health checks and the main on/off switch; **Rules**
+(what to report, how often, how much text, reply control); **Activity** with per-project switches and the latest chats;
+and **Connection** with provider presets, the device name and a test button. It listens on `127.0.0.1` only, with a
+one-time sign-in link, CSRF protection and a strict content security policy.
+
+The page, the mails and the command line follow the `language` setting: `auto` (the default), `it` or `en`. `auto`
+uses the language set in Claude Code's own `language` setting when it names Italian or English, and otherwise the
+system language. The page is translated from static catalogs in the package. Nothing is sent to a translation
+service, and data from the daemon (project names, chat titles, mail subjects) is never translated.
+
+### Reply by mail
+
+Off by default (web app → Rules → *Control by replying to the e-mail*). When on, ccmail reads your mailbox over IMAP
+and accepts only replies that come from you, are verified by the provider, quote a valid reference from a recent
+ccmail mail, and start with `OFF`, `ON` or `PAUSE [minutes]` (the Italian words `SPEGNI`, `ACCENDI`, `PAUSA`, and a few
+others are accepted too). With **Replies reach Claude** on, any other reply text is delivered to the chat the mail came
+from. The answer to it is mailed back to you when that turn ends, even if it was short, with the subject
+"answer to your e-mail" (Italian: "risposta alla tua email").
+
+See [SECURITY.md](SECURITY.md) for the exact rules and [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md) for the delivery
+paths.
+
+### The `/mail-notify` skill
+
+`mail-notify install-skill` copies a small skill to `~/.claude/skills/mail-notify/`. It lets you type
+`/mail-notify on`, `off`, `status`, `test` or `open` in Claude Code, and tells Claude how to behave during long
+processes (a concise status while they run, a short final summary). The skill is instructed never to read credential
+files or edit Claude's settings.
+
+## Several computers
+
+Every computer has its own daemon, data folder and credentials, and its own copy of the settings. Give each one a name
+(`mail-notify init`, or web app → Connection → *Name of this device*) and it appears as `Device:` in the mails. A reply
+is applied by the daemon that sent the mail it refers to; daemons ignore references they did not issue.
+
+## Platforms
+
+| | Windows | macOS | Linux |
+|---|---|---|---|
+| Data folder | `%APPDATA%\ccmail` | `~/Library/Application Support/ccmail` | `~/.config/ccmail` |
+| Password store | Credential Manager (fallback: DPAPI file) | Keychain (fallback: 0600 file) | Secret Service via `secret-tool` (fallback: 0600 file) |
+| Start at logon | Task Scheduler | LaunchAgent | `systemd --user` (fallback: XDG autostart) |
+| Status | tested | to be tested (later release) | to be tested (later release) |
+
+The fallback files are announced loudly by `init`, `status`, `doctor` and the web app. On Linux install
+`libsecret-tools` to use the Secret Service. Claude Code's folder honours `CLAUDE_CONFIG_DIR`.
+
+## Privacy and security
+
+- ccmail reads only what it needs: what Claude Code passes to its hooks; the desktop app's chat titles and folders; the
+  latest chat title recorded at the end of a session transcript, when the app's metadata is missing; the account's
+  display name from `~/.claude.json` (nothing else in that file is used); and the `language` key of Claude Code's
+  `settings.json`. Installing the hooks edits that file, after making a backup.
+- Message text is redacted for common secrets before it is put in a mail. `title` and `minimal` content modes send no
+  model-written text at all.
+- The password is never written to logs, the database, the repository or the web app; the API never returns it.
+- The daemon binds to `127.0.0.1`, authenticates hooks with a file-based token and checks `Host` and `Origin`.
+
+Details and the threat model: [SECURITY.md](SECURITY.md). Report vulnerabilities privately (see that file).
+
+## Troubleshooting
+
+| Symptom | Try |
+|---|---|
+| No mail at all | `mail-notify status`: notifications start OFF, so run `mail-notify on`. Then `mail-notify doctor --network` and `mail-notify test`; check spam and the app password |
+| Hooks do nothing | `mail-notify install-hooks`, then restart Claude Code; `mail-notify doctor` flags a moved Python |
+| No buttons or cards in a mail | Cards need HTML mail and reply control on; plain-text mail apps show no buttons |
+| Chat names missing | `mail-notify diagnose` shows where the desktop app's metadata is looked for |
+| Port busy | The daemon picks a free port by itself; hooks and CLI read it from `daemon.json` |
+| Reply by mail is slow | Most of the delay is the provider delivering mail to yourself (seconds to about 25 s) |
+| Linux: password in a file | Install `libsecret-tools` and run `mail-notify init` again |
+
+## Commands
+
+`init` · `setup [--autostart]` · `on` · `off` · `status [--cwd DIR]` · `test` · `open` · `stop` · `doctor [--network]` · `install-hooks
+[--autostart]` · `uninstall-hooks [--autostart]` · `install-skill` · `uninstall-skill` · `diagnose` · `trace on|off|show`
+· `migrate` · `daemon [--foreground]` · `install-cli` · `uninstall-cli`.
+
+The command is installed as both `mail-notify` and `ccmail`. `install-hooks` and `install-skill` also create the short
+`mail-notify` command. If neither name is found, run `python -m ccmail install-cli` once (see Step 1).
+
+## Resource use
+
+No model calls at all in normal operation. The daemon uses about 35 MB and about 0.05–0.25 % of one core, and each hook
+call adds about 0.12 s. Tokens are spent only on the skill text, on periodic wake-ups while background tasks run and on
+delivered replies. The HTML mail costs no tokens (about 0.1–0.6 ms of CPU and 6–9 KB more per mail). Measurements,
+formulas and limits: [docs/RESOURCES.md](docs/RESOURCES.md).
+
+## How it works
+
+Hooks run a tiny client (`python -m ccmail hook`) that forwards the event to the local daemon and always exits 0. The
+daemon applies the rules, writes to SQLite, and an outbox worker sends mail with retries. More in
+[docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md).
+
+## Development
+
+```bash
+git clone https://github.com/lobascioemanuele-droid/mail-notify && cd mail-notify
+```
+
+```bash
+python -m venv .venv
+```
+
+```bash
+. .venv/bin/activate
+```
+
+On Windows, activate with `.venv\Scripts\activate` instead.
+
+```bash
+pip install -e .
+```
+
+```bash
+python -W ignore -m unittest discover -s tests
+```
+
+Set `PYTHONPATH=src:tests` first if the package is not installed.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md); what 1.x promises to keep
+stable is in [docs/STABILITY.md](docs/STABILITY.md).
+
+## License
+
+[MIT](LICENSE).