{"id":51106134,"url":"https://github.com/xiaotianxt/mimestreamctl","last_synced_at":"2026-06-24T14:01:17.262Z","repository":{"id":351415131,"uuid":"1210901636","full_name":"xiaotianxt/mimestreamctl","owner":"xiaotianxt","description":"AI-native control plane for Mimestream on macOS.","archived":false,"fork":false,"pushed_at":"2026-04-29T23:22:00.000Z","size":62,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T01:25:25.684Z","etag":null,"topics":["accessibility","ai-agent","applescript","automation","cli","email","macos","mimestream"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xiaotianxt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T21:50:46.000Z","updated_at":"2026-04-29T23:22:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xiaotianxt/mimestreamctl","commit_stats":null,"previous_names":["xiaotianxt/mimestreamctl"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/xiaotianxt/mimestreamctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotianxt%2Fmimestreamctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotianxt%2Fmimestreamctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotianxt%2Fmimestreamctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotianxt%2Fmimestreamctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xiaotianxt","download_url":"https://codeload.github.com/xiaotianxt/mimestreamctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xiaotianxt%2Fmimestreamctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34735266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","ai-agent","applescript","automation","cli","email","macos","mimestream"],"created_at":"2026-06-24T14:01:15.998Z","updated_at":"2026-06-24T14:01:17.257Z","avatar_url":"https://github.com/xiaotianxt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mimestreamctl\n\nAI-native control plane for `Mimestream` on macOS.\n\n`mimestreamctl` gives terminal workflows and AI agents a thin, predictable way to operate the local `Mimestream` app. It fills the gap between Mimestream's very small AppleScript surface and the actions an agent actually needs in practice: read the selected message, inspect durable links, draft replies, move threads, and trigger common mailbox actions.\n\nIt is deliberately small, local-first, and production-friendly.\n\n## Why This Exists\n\n`Mimestream` is great for humans, but not very agent-shaped.\n\nThis project wraps three primitives into one stable CLI:\n\n- `AppleScript` for current selection and app activation\n- `System Events` for menu-driven actions and paste/send flows\n- macOS Accessibility APIs for fast message body extraction\n\nThe result is a lightweight interface that works well under Codex, shell scripts, and other AI-native automations.\n\n## What It Can Do\n\n- Read the selected message as `markdown`, `plain`, or `json`\n- List the latest `N` rows or all rows from the current message table\n- Search the local Mimestream cache without depending on the front UI window\n- Plan and execute safe unsubscribe actions from `List-Unsubscribe` headers or clear body links\n- Extract stable links for the current message\n- Reply or reply-all with generated text\n- Move the current thread to a mailbox or label\n- Archive, mark read, star, trash, or report spam\n- Draft a new message via `mailto:`\n- Ship with a bundled Codex skill in [`skills/mimestreamctl`](./skills/mimestreamctl)\n\n## Requirements\n\n- macOS desktop session\n- `Mimestream` installed\n- Terminal automation/accessibility permissions:\n  - Accessibility access\n  - Automation permission for `System Events`\n  - Automation permission for `Mimestream`\n\nMenu-driven commands assume `Mimestream` is using English menu names.\n\n## Install\n\nClone the repo and run the CLI directly:\n\n```bash\ngit clone https://github.com/xiaotianxt/mimestreamctl.git\ncd mimestreamctl\n./mimestreamctl --help\n```\n\nNo third-party Python dependencies are required.\n\n## Codex Skill\n\nThis repo also includes a Codex skill so an agent can invoke the tool with a stronger task-specific prompt and a stable wrapper.\n\nInstall it by symlinking the bundled skill:\n\n```bash\nmkdir -p ~/.codex/skills\nln -s \"$(pwd)/skills/mimestreamctl\" ~/.codex/skills/mimestreamctl\n```\n\nThe bundled wrapper resolves the repo-relative CLI automatically, so the symlinked skill can call the checked-out project directly.\n\n## Common Flows\n\nRead the currently selected message:\n\n```bash\n./mimestreamctl read\n./mimestreamctl read --json\n./mimestreamctl read --full --json\n./mimestreamctl links\n./mimestreamctl links --resolve-redirects --json\n```\n\nList the current mailbox rows:\n\n```bash\n./mimestreamctl list\n./mimestreamctl list 100 --json\n./mimestreamctl list latest 250\n./mimestreamctl list all --format plain\n```\n\n`list` defaults to the latest `100` rows. `list all` walks every row currently exposed through Accessibility, so it can take noticeably longer on large mailboxes.\n\nSearch the local mail cache:\n\n```bash\n./mimestreamctl mail accounts\n./mimestreamctl mail search --account gmail --from openai --since 7d --limit 10\n./mimestreamctl mail get --id 19244 --links\n```\n\nPlan and execute unsubscribe actions:\n\n```bash\n./mimestreamctl mail unsubscribe --account gmail --from openai --since 7d --dry-run\n./mimestreamctl mail unsubscribe --account gmail --from openai --since 7d --confirm\n```\n\n`mail unsubscribe` prefers machine-readable `List-Unsubscribe` headers. If a message has no usable header, it can fall back to unsubscribe links in the HTML/text body and follow simple unsubscribe confirmation forms or links. It does not handle JavaScript-only pages, CAPTCHAs, or sign-in-required flows; those return a non-success status for manual handling. Tokenized unsubscribe URLs are redacted by default; pass `--show-urls` only when you intentionally need full URLs.\n\nReply to the selected message:\n\n```bash\n./mimestreamctl reply --body-file /tmp/reply.txt\n./mimestreamctl reply --body-file /tmp/reply.txt --send --confirm\n```\n\nMove or archive the current thread:\n\n```bash\n./mimestreamctl move \"Receipts\"\n./mimestreamctl archive\n./mimestreamctl mark-read\n```\n\nDraft a new message:\n\n```bash\n./mimestreamctl compose \\\n  --to someone@example.com \\\n  --from someone@work.com \\\n  --subject \"Quick follow-up\" \\\n  --body-file /tmp/message.txt\n```\n\n`--from` selects one sender identity from the compose window. It accepts either the full visible label or a unique substring such as an email address.\n\n## Commands\n\n- `selection`\n- `list [latest [count]|count|all]`\n- `mail accounts`\n- `mail search`\n- `mail get --id \u003cid\u003e`\n- `mail unsubscribe --dry-run|--confirm`\n- `read`\n- `links`\n- `activate`\n- `menus`\n- `click \u003cmenu\u003e \u003citem\u003e`\n- `go \u003cinbox|starred|sent|all-mail|spam|trash\u003e`\n- `move \u003cdestination\u003e`\n- `compose`\n- `insert-text`\n- `archive`\n- `mark-read`\n- `mark-all-read`\n- `star`\n- `important`\n- `reply [--body|--body-file] [--send --confirm]`\n- `reply-all [--body|--body-file] [--send --confirm]`\n- `forward`\n- `move-to-inbox`\n- `not-spam`\n- `new-message`\n- `trash --confirm`\n- `spam --confirm`\n- `send --confirm`\n- `send-and-archive --confirm`\n\n## Output Modes\n\n- `read` defaults to `markdown`\n- `read` now defaults to the fast AX path\n- use `--full` to include `sender`, `date`, and `preview`\n- `read` and `links` now expose `body_links` for links found inside the message body\n- use `--resolve-redirects` to follow tracking URLs and surface a `resolved_url` when available\n- use `--format plain` for a simpler text view\n- use `--json` for structured output\n- use `links` when only URLs are needed\n\nKnown link fields:\n\n- private `links.mimestream.com` URL\n- `mimestream:///open/...` deep link\n- Gmail URL derived from the current selection\n\n## Design Notes\n\n- `read` uses the Swift Accessibility helper by default and avoids the older slow row metadata path\n- `read --full` still uses the Swift Accessibility helper, but also asks it for extra row metadata\n- body extraction reads the message `AXWebArea` directly, so it does not depend on keyboard focus being in the message body\n- destructive or sending actions require explicit `--confirm`\n- `mail unsubscribe` also requires `--confirm` unless `--dry-run` is used\n- `insert-text` restores the previous clipboard contents by default\n\n## Caveats\n\n- This is local macOS automation, not an official Mimestream API\n- UI structure changes in future Mimestream releases may require locator updates\n- `mail` commands read Mimestream's local SQLite cache, so results reflect what Mimestream has already synced\n- `move` depends on the current `Move to...` destination matching behavior in Mimestream\n- automation must run inside the logged-in desktop session\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaotianxt%2Fmimestreamctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxiaotianxt%2Fmimestreamctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxiaotianxt%2Fmimestreamctl/lists"}