Add a README

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander "PapaTutuWawa"
+
+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.

README.md

@@ -0,0 +1,37 @@
+# Agent Mail Sorter
+
+I just wanted to try writing an agent once, okay?
+
+It takes in your IMAP credentials, mirrors the IMAP folders into memory
+and then tells the LLM to sort the mails into (new) folders from the Inbox.
+The agent cannot modify your real Inbox and only ever acts on the in-memory clone.
+
+## Usage
+
+Install the dependencies using uv: `uv sync`. Then you can run
+`uv run imap-sorter` to run the agent. Use `-h` for the list of parameters the script
+takes:
+
+```
+  -h, --help           show this help message and exit
+  --username USERNAME  IMAP username
+  --password PASSWORD  IMAP password
+  --host, -H HOST      IMAP host
+  --port, -P PORT      IMAP port
+  --data, -d DATA      Instead of querying the IMAP server, use this JSON file
+  --output, -o OUTPUT  Dump the agent's operations into this JSON file
+  --url, -u URL        URL to an OpenAI-compatible inference endpoint
+  --api-key API_KEY    API key to use with the OpenAI-compatible endpoint
+  --model MODEL        Model name to use
+```
+
+Important to note that if you want preview what the agent has done afterwards, specify
+`--output` to output the operations the agent performed into a JSON file. You can then
+use `uv run imap-sorter-preview` to preview how the server would look like after the agent's
+operations. This requires the `data.json` file that logging into the IMAP server will create.
+
+## License
+
+Written by a human :)
+
+Licensed under MIT. See [LICENSE.md](./LICENSE.md).

pyproject.toml

@@ -13,7 +13,7 @@ dev = [
 ]
 
 [project.scripts]
-imap_sorter = "imap_sorter.main:main"
+imap-sorter = "imap_sorter.main:main"
 imap-sorter-preview = "imap_sorter.scripts.preview:main"
 
 [tool.uv]