1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
# mailctl
A deliberately narrow, agent-safe CLI wrapper around [notmuch](https://notmuchmail.org/), meant for use by AI coding agents (Claude Code, opencode, etc.) to **search and organize** local mail. It has no ability to send: there is no SMTP, reply, or compose code path in the tool at all.
## Why
An agent given raw `notmuch`/`mbsync` access can do anything, including mangle tags across every account or trigger a sync at the wrong moment. `mailctl` closes that surface:
- **Reads run freely**, mutations are gated.
- **Tag changes are dry-run by default**, and only touch the index with `--apply`.
- **Cross-account mutations require an explicit opt-in** (`--all-accounts`); the default forces a single `--account`.
- **Destructive changes** (adding `deleted`/`trash`/`spam`, removing `inbox`) need `--apply` **and** `--confirm-destructive`.
- **Every applied mutation is audited** to `~/.local/state/mailctl/audit.log`.
- **Drafting is possible, sending is not.** `mailctl draft` writes a local-only message into the account's Drafts folder for you to review and send yourself in neomutt.
## Requirements
- `notmuch` on `PATH`, with a synced Maildir at `~/Mail` (see Configuration).
- Python 3 (standard library only, no third-party packages).
## Installation
No installer, just copy files into place:
```bash
cp mailctl.py mailsync.sh ~/bin/ # executables
cp -r mail-organize ~/.claude/skills/ # Claude Code skill, in its own dir
```
The skill invokes the tool at `~/bin/mailctl.py`; keep that path.
## Configuration
Your accounts are not in the source. `mailctl` reads them from `~/.config/mailctl/accounts.json` (override with the `MAILCTL_CONFIG` environment variable):
```json
{
"accounts": {
"work": {
"maildir": "work-mbsync-dir",
"address": "you@example.org",
"drafts": "Drafts"
},
"personal": {
"maildir": "personal-mbsync-dir",
"address": "you@example.net",
"drafts": null
}
}
}
```
- `maildir` is the account's subdirectory under `~/Mail`, exactly as mbsync created it.
- `address` is the real From address, used only when writing a draft.
- `drafts` is the Drafts folder name inside that maildir, matching the account's mbsync `Patterns` (`Drafts`, `[Gmail]/Bozze`, ...). Use `null`, or omit it, if that account has no synced Drafts folder; `mailctl draft` then refuses that account.
The account map stays a closed set. The config is checked against its schema **and** against the actual directories on disk when `mailctl` starts, and any problem is a hard exit before a query runs: a misspelled `maildir` can't silently produce a filter matching nothing, and a misspelled `drafts` can't put a draft somewhere mbsync never syncs. Set `MAILCTL_MAIL_ROOT` if your Maildir is not at `~/Mail`.
## Usage
```bash
mailctl search "<notmuch query>" [--account NAME] [--json]
mailctl show "<thread:id or id:msgid>"
mailctl tags # list all tags in use
mailctl count "<query>" [--account NAME]
mailctl senders "<query>" [--account NAME] [--top N] [--json] # ranked by count
mailctl subjects "<query>" [--account NAME] [--top N] [--json] # subject terms
mailctl tag "<query>" --account NAME [--add TAG]... [--remove TAG]...
[--apply] [--confirm-destructive]
mailctl draft --account NAME --to ADDR --subject TEXT
[--cc ADDR] [--body TEXT | --body-file PATH]
```
Reads default to global scope (all accounts) when `--account` is omitted. `tag` refuses to run without either `--account NAME` or `--all-accounts`.
### Example
```bash
# Preview: what would tagging these as 'newsletter' touch?
mailctl tag "from:substack.com" --account personal --add newsletter
# Commit it after reviewing the preview
mailctl tag "from:substack.com" --account personal --add newsletter --apply
```
## Companion sync script
`mailsync.sh` runs `mbsync -a` followed by `notmuch new`, with a `flock` guard and timestamped, rotated logging. It is meant for a cron/systemd timer and is **not** called by `mailctl.py`; sync and organization stay separate on purpose.
## Claude Code skill
`mail-organize/` is a Claude Code skill that makes `mailctl` the only sanctioned interface for an agent to touch your mail, and tightens the tool's gates into workflow rules (always dry-run first, never sync, never send, single-account scope). See `mail-organize/SKILL.md`.
## License
Copyright (C) 2026 Danilo M. <danix@danix.xyz>
Released under the **GNU General Public License, version 2** (GPLv2-only). See
[`LICENSE`](LICENSE) for the full text.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
## Development Approach
This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.
|
