Przejdź do treści
Biblioteka skilli
AI i agenci · Integracja z narzędziem

th-mail

/th-mail

Włącza nasłuchiwanie poczty między agentami w tle, wyświetla wiadomości i pozwala na nie odpowiadać podczas innej pracy.

Repozytorium
smooth ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: watch-once.sh, watch-once.test.sh

Co robi i kiedy

Włącza nasłuchiwanie poczty między agentami w tle, wyświetla wiadomości i pozwala na nie odpowiadać podczas innej pracy.

Oryginalny opis (EN)

Bring this Claude Code session online as a `th` agent and listen for agent-to-agent mail in the BACKGROUND while you keep doing other work — surfacing (and, when you can, responding to) messages as they arrive. Uses the `th msg` / `th agent` system (harness-agnostic, machine-level SQLite mailbox). Invoke as `/th-mail` (start listening), `/th-mail send <to> <body>`, `/th-mail status`, or `/th-mail stop`. Use when the user wants you to be reachable by / coordinate with other agents while working.

Jak działa

  1. /th-mail or /th-mail start [handle] — go online and listen
  2. /th-mail send <to> <body> — send / broadcast
  3. /th-mail status — who's around / what's waiting
  4. /th-mail stop — go offline
  5. Notes & footguns
Sekcje z nagłówków SKILL.md, w oryginale · 56 linii, 1 101 słów
Podgląd SKILL.md
---
name: th-mail
description: Bring this Claude Code session online as a `th` agent and listen for agent-to-agent mail in the BACKGROUND while you keep doing other work — surfacing (and, when you can, responding to) messages as they arrive. Uses the `th msg` / `th agent` system (harness-agnostic, machine-level SQLite mailbox). Invoke as `/th-mail` (start listening), `/th-mail send <to> <body>`, `/th-mail status`, or `/th-mail stop`. Use when the user wants you to be reachable by / coordinate with other agents while working.
---

# th-mail — be reachable by other agents while you work

`th` ships a harness-agnostic agent mailbox (`th agent` registry + `th msg` mail). Since pearl th-374f85 it lives in **one SQLite file per machine** (`~/.smooth/mail.db`), not the per-repo pearl store of old — so every agent on this host shares one mailbox no matter which repo or worktree it is standing in, sends are instant local writes, and concurrent agents no longer wedge each other. This skill registers the current session as a named agent and runs a **background watcher** so you can keep working and still pick up mail the moment it arrives.

**Listening is on by default (SMOODEV-3356).** The SessionStart hook tells every interactive session to arm the watcher, and `hooks/mail-guard.sh` backs it up: it surfaces unread wake-worthy mail on each prompt (direct mail and broadcast request/handoff/cancel; broadcast notes stay in the inbox without nudging), reminds an unarmed session once, and before a session goes idle it blocks only for unread direct mail. `/th-mail` is still how you re-arm by hand, send, or check status. Opt a session out with `SMOOTH_MAIL_WATCH=0`.

**The core mechanism:** `th msg watch --once --json` blocks until unread mail appears, prints it, and **exits**. A Claude Code background Bash task re-invokes you when it exits — so an arriving message _pulls you back in_ without busy-polling. You handle it, **re-arm the watcher**, and return to whatever you were doing. Listening is ancillary; it must never block your primary work.

**Start by finding out who you are — never assume a handle.** `th agent whoami` prints it, resolved as `$SMOOTH_AGENT_HANDLE` → `$SMOOTH_AGENT` → the handle the SessionStart hook recorded for this session → `user@host`. Every `th msg` / `th agent` command with no `--agent` / `--from` resolves it the same way, so **bare commands read your own mailbox** — you no longer have to thread `--agent` through every call. A handle taken from a doc, an example, or a previous session is a guess, and guessing is how a session reads an empty inbox while its real mail piles up under the name it actually registered (pearl th-fa9f40).

## `/th-mail` or `/th-mail start [handle]` — go online and listen

1. **Read your handle first:** `th agent whoami` (`--json` to parse). The SessionStart hook already registered you, under a placeholder like `cc-<repo>-<sid4>` unless you were launched with one.
2. **Claim a task-meaningful handle:** `th agent claim <handle>` — it renames you and carries your mail across. Use `claim`, never `th agent register --name <something-else>`: registering a different name gives this session a _second_ mailbox that nobody watches, which `register` now refuses without `--force`.
3. **Scan current mail** so nothing already waiting is missed:
   `th msg inbox --brief` (surface bounded previews; fetch only selected full
   bodies with `th msg thread <id>`)
4. **Arm the background watcher** — run with `run_in_background: true`:
   `bash "${CLAUDE_PLUGIN_ROOT}/skills/th-mail/watch-once.sh" <handle> 15`
   (args: handle — pass the one from step 1/2, poll-interval-secs; optional 3rd = max lifetime secs, default 24h)
5. Tell the user: _online as `<handle>`, listening in the background — continuing with <current work>._ Then **go back to your primary task.**

### When the watcher background task completes (you get re-invoked)

1. Read the task's output. `[]` **with exit 0** → timed out, just **re-arm** and continue. A **non-zero exit** means the mail store failed (full disk, unreadable `~/.smooth/mail.db`): your mail state is _unknown_, not empty — say so and fix it rather than re-arming into the same failure.
2. Otherwise, for each bounded preview:
    - **Surface it** concisely: from, type, preview, thread id.
    - **Fetch only what you need**: `th msg thread <id>` gets the full message/thread; MCP users can call `mail_get(message_id)`.
    - **Triage & respond**: answer what you can (`th msg reply <msg-id> --from <handle> --body "..."`, or `th msg send <sender> "..." --from <handle>`); surface and ask when it needs the user's decision.
3. **Acknowledge:** `th msg ack --all --agent <handle>` (or `th msg ack <id>…`) so you don't re-raise it. Acks are **per-recipient** — acking a broadcast consumes only your copy, never anyone else's.
4. **Re-arm** the watcher and **return to your primary task.**

> Keep doing your real work between mail events. The watcher is a tap on the shoulder, not a foreground loop.

## `/th-mail send <to> <body>` — send / broadcast

`th msg send <to|all> <body...> --from <handle>`. Optional `--type note|request|result|handoff|cancel` (how the recipient should triage it), `--priority N` (higher sorts first in their inbox), `--re <id>` to reply within a thread. `--to`/`--body` flag forms still work.

## `/th-mail status` — who's around / what's waiting

`th agent list` (registered agents, presence, branch, current task) and `th msg inbox --agent <handle>`. Publish your own presence with `th agent status --status working --task "what I'm doing"` so other agents can see whether you're free.

## `/th-mail stop` — go offline

Kill the background watcher task (via the harness's background-task controls), then `th agent offline --name <handle>`.

## Notes & footguns

- **Identity:** the watcher and every `th msg` call must use the **same `--agent <handle>`**, or you'll watch the wrong mailbox. `th agent whoami` tells you what you resolve to right now.
- **`--pull` / `--no-pull` / `--no-push` are dead flags.** They still parse (so old scripts don't break) and print a deprecation note, but they do nothing: the mailbox is machine-local, there is no remote to sync and no write lock to contend for. The old advice about `Error 1105: database is read only` and avoiding concurrent `--pull` watchers no longer applies.
- **Don't double-arm:** keep exactly one watcher background task alive.
- **`th msg inbox` vs `th inbox`:** this skill is `th msg` (agent-to-agent mail). `th inbox` is the same mailbox for your default handle; operative review gates are a different thing.
- **MCP tools do the same thing without shelling out.** If `th mcp install --harness claude-code` has been run (or you're using this plugin's bundled `smooth` MCP server), `agent_identity` / `agent_status` / `agent_list` / `mail_inbox` / `mail_get` / `mail_send` / `mail_ack` are available as tools. `mail_inbox` returns at most 10 messages with 240-character previews by default; fetch selected full bodies with `mail_get`. They hit the same `~/.smooth/mail.db`. Use whichever is at hand — but the **background watcher** has no MCP equivalent, so `/th-mail` still owns being _pushed_ mail rather than polling for it.
- **Cloud sync is optional.** Everything above works with no Smoo account. `th agent backend set cloud` (see `th agent backend status`) moves the mailbox to api.smoo.ai so agents on _different machines_ share it; that one is a paid feature with a 14-day trial. Nothing local depends on it.
Pliki w paczce (3)
  • SKILL.md 7 KB
  • watch-once.sh 3 KB
  • watch-once.test.sh 3 KB

Wersje

W bazie nie ma innych skilli o nazwie th-mail.

Migawka bazy z 13.11.2026 · wersja paczki b92076e0b7a1 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90msg
    Wysyła i czyta wiadomości między sesjami Claude Code przez skrzynkę @id i pokazuje, kto jest osiągalny.
  • 100msg
    Obsługuje komunikację między agentami przez CLI msg: wysyłanie wiadomości do innych sesji agentów, czytanie przychodzących i koordynację z agentami w panelach tmux.
  • 100pigeon
    Wysyła i odbiera wiadomości między sesjami Claude Code w różnych katalogach projektów przez globalną bazę SQLite ~/.claude/pmail.db.
  • 100agent-comms
    Koordynuje pracę z orkiestratorem i innymi agentami przez magistralę th-mail: rejestruje tożsamość, publikuje obecność, raportuje status i przekazuje zadania.
  • 100agent-mailbox
    Wysyła i odbiera wiadomości między agentami AI przez wspólną skrzynkę: rejestracja, pętla czytaj-działaj-odpowiedz i zasady postępowania.
  • 100receive
    Odbiera przychodzące wiadomości retalk od wskazanych nadawców, jednorazowo albo w tle, i pokazuje rozmowę jako czytelny zapis.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.