Skip to content
Back to search

agent-cli-plugins

MarketplaceWorks with Claude CodeGitHub

Agent-optimized CLIs for Apple Mail, Notes, Calendar, Reminders and Paperless-ngx, each with a Claude Code skill and policy guard, plus a shared agent-cli skill.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bam679--agent-cli-plugins/badge.svg)](/listings/bam679--agent-cli-plugins)

HTML

<a href="/listings/bam679--agent-cli-plugins"><img src="/api/listings/bam679--agent-cli-plugins/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the CLIs you want, for example with Homebrew:

brew install Bam679/tap/apple-mail Bam679/tap/apple-reminders

Each CLI's README also describes the signed release archives and `go install`.

Then add the marketplace and the plugins:

claude plugin marketplace add Bam679/agent-cli-plugins
claude plugin install agent-cli@agent-cli-plugins         # shared skill and detection
claude plugin install apple-mail@agent-cli-plugins        # one plugin per CLI you use
claude plugin install apple-reminders@agent-cli-plugins

Every CLI repository is also a marketplace of its own (`claude plugin marketplace add Bam679/apple-mail-cli`). Install each plugin from one source only: when the same plugin comes from two marketplaces, Claude Code runs the hooks of just one copy.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 71 lines
  1. {
  2. "name": "agent-cli-plugins",
  3. "owner": {
  4. "name": "Bam679",
  5. "url": "https://github.com/Bam679"
  6. },
  7. "description": "Agent-optimized CLIs for Apple Mail, Notes, Calendar, Reminders and Paperless-ngx, each with a Claude Code skill and policy guard, plus a shared agent-cli skill.",
  8. "plugins": [
  9. {
  10. "name": "agent-cli",
  11. "source": "./plugins/agent-cli",
  12. "description": "Shared skill and session-start detection for all agent-cli tools.",
  13. "category": "productivity"
  14. },
  15. {
  16. "name": "apple-mail",
  17. "source": {
  18. "source": "git-subdir",
  19. "url": "https://github.com/Bam679/apple-mail-cli.git",
  20. "path": "plugin",
  21. "ref": "v0.2.0"
  22. },
  23. "description": "Apple Mail: read and triage mail; never sends.",
  24. "category": "productivity"
  25. },
  26. {
  27. "name": "apple-notes",
  28. "source": {
  29. "source": "git-subdir",
  30. "url": "https://github.com/Bam679/apple-notes-cli.git",
  31. "path": "plugin",
  32. "ref": "v0.2.0"
  33. },
  34. "description": "Apple Notes: list, search, read; policy-gated create/append/move.",
  35. "category": "productivity"
  36. },
  37. {
  38. "name": "apple-calendar",
  39. "source": {
  40. "source": "git-subdir",
  41. "url": "https://github.com/Bam679/apple-calendar-cli.git",
  42. "path": "plugin",
  43. "ref": "v0.1.0"
  44. },
  45. "description": "Apple Calendar: events and search; policy-gated create/update/delete.",
  46. "category": "productivity"
  47. },
  48. {
  49. "name": "apple-reminders",
  50. "source": {
  51. "source": "git-subdir",
  52. "url": "https://github.com/Bam679/apple-reminders-cli.git",
  53. "path": "plugin",
  54. "ref": "v0.1.0"
  55. },
  56. "description": "Apple Reminders: lists and due tasks; policy-gated add/complete.",
  57. "category": "productivity"
  58. },
  59. {
  60. "name": "paperless",
  61. "source": {
  62. "source": "git-subdir",
  63. "url": "https://github.com/Bam679/paperless-cli.git",
  64. "path": "plugin",
  65. "ref": "v0.1.0"
  66. },
  67. "description": "Paperless-ngx: search, read and download documents; policy-gated upload/tagging.",
  68. "category": "productivity"
  69. }
  70. ]
  71. }
README.md · README · 128 lines
  1. # agent-cli-plugins
  2. A Claude Code marketplace for five small CLIs that let AI agents work with Apple Mail, Notes, Calendar, Reminders and Paperless-ngx.
  3. [![ci](https://github.com/Bam679/agent-cli-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/Bam679/agent-cli-plugins/actions/workflows/ci.yml)
  4. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Bam679/agent-cli-plugins/badge)](https://scorecard.dev/viewer/?uri=github.com/Bam679/agent-cli-plugins)
  5. [![licence](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
  6. <picture>
  7. <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
  8. <img alt="agent-cli logo: a prompt chevron between square brackets" src="assets/logo.svg" height="56">
  9. </picture>
  10. ## About
  11. This repository is the entry point to the agent-cli family. It holds the marketplace that lists all five plugins, a shared skill that teaches agents the common rules once, and the shared Go code and repository template that keep the five CLIs consistent.
  12. | CLI | What an agent can do with it | Repository |
  13. |---|---|---|
  14. | `apple-mail` | List, search and read mail; save drafts; mark, flag, move and trash. It cannot send. | [apple-mail-cli](https://github.com/Bam679/apple-mail-cli) |
  15. | `apple-notes` | Search and read notes; create, append and move them | [apple-notes-cli](https://github.com/Bam679/apple-notes-cli) |
  16. | `apple-calendar` | Read and search events; create, update and delete them | [apple-calendar-cli](https://github.com/Bam679/apple-calendar-cli) |
  17. | `apple-reminders` | Read lists and due tasks; add, complete and update reminders | [apple-reminders-cli](https://github.com/Bam679/apple-reminders-cli) |
  18. | `paperless` | Search, read and download documents; upload and tag them | [paperless-cli](https://github.com/Bam679/paperless-cli) |
  19. ## Why a CLI instead of an MCP server
  20. There are MCP servers for some Apple apps, but each tool call goes back through the model, and the tool definitions fill the context before the agent has done anything. With a CLI, the agent learns the commands from a short skill, filters the output with `jq` or `grep`, and chains several steps in one script, for example turning this week's events into reminders in a single run. That is faster and uses far fewer tokens. Single-purpose CLIs exist for some of these apps, but not as a set with one output format and one permission model, which is what you need to let Claude manage everyday things on a Mac.
  21. ## Features
  22. - One output format for all five tools: text lines, JSON or NDJSON, with field selection, paging and size limits
  23. - Read-only by default; writes need a policy file and `--confirm`, and every write can be previewed with `--dry-run`
  24. - The same exit codes everywhere, so an agent knows whether to fix a flag, stop, or ask the user
  25. - A shared skill that loads the reference for one tool only when the agent needs it, and a session-start hook that tells the agent which CLIs are installed
  26. - Signed releases with SBOMs and build provenance, and no third-party Go dependencies
  27. ## Installation
  28. Install the CLIs you want, for example with Homebrew:
  29. ```sh
  30. brew install Bam679/tap/apple-mail Bam679/tap/apple-reminders
  31. ```
  32. Each CLI's README also describes the signed release archives and `go install`.
  33. Then add the marketplace and the plugins:
  34. ```sh
  35. claude plugin marketplace add Bam679/agent-cli-plugins
  36. claude plugin install agent-cli@agent-cli-plugins # shared skill and detection
  37. claude plugin install apple-mail@agent-cli-plugins # one plugin per CLI you use
  38. claude plugin install apple-reminders@agent-cli-plugins
  39. ```
  40. Every CLI repository is also a marketplace of its own (`claude plugin marketplace add Bam679/apple-mail-cli`). Install each plugin from one source only: when the same plugin comes from two marketplaces, Claude Code runs the hooks of just one copy.
  41. ## Usage
  42. Once the plugins are installed, ask Claude in plain language, for example "Which reminders are due this week?" or "File the latest invoice from my mailbox in Paperless". The skills tell the agent which commands to run. You can run the same commands yourself:
  43. ```sh
  44. apple-reminders list --due-before +7d
  45. apple-calendar events --from today --to +7d --json --fields start,title
  46. apple-mail search invoice --since -30d --limit 5
  47. ```
  48. At the start of every session the `agent-cli` plugin prints a line such as `agent-cli tools installed: apple-mail@0.1.0 apple-reminders@0.1.0; not installed: apple-notes …`, so the agent knows what it can use.
  49. ## Permissions
  50. Every CLI only reads until you allow writes in `~/.config/agent-cli/<tool>.json`. The binary enforces that file, so the rules hold under every agent, and no flag or environment variable can widen them. A write is checked against the policy, previewed with `--dry-run` and applied with `--confirm`.
  51. ```json
  52. {
  53. "version": 1,
  54. "operations": { "allow": ["read", "add", "complete"], "deny": ["delete"] },
  55. "scopes": { "write": { "allow": ["Agent*"] }, "read": { "deny": ["Health*"] } },
  56. "limits": { "max_write_batch": 10 }
  57. }
  58. ```
  59. For Claude Code, `<tool> policy --claude-settings` prints recommended settings: read commands allowed, write commands ask first, the policy directory protected, and the Bash sandbox enabled with only the CLI excluded. In the sandbox an agent cannot reach Apple Events, the network or the policy file directly, so the CLI and its policy are the only way to your data.
  60. [ADR-0003](docs/adr/0003-permission-model.md) records the decision, and [Is a binary-enforced policy overkill?](docs/explanation/permission-research.md) compares it with a dozen similar tools.
  61. ## Threat model
  62. | Threat | Mitigation |
  63. |---|---|
  64. | Prompt injection through mail, notes or documents | Writes are off by default and checked in the binary. Skills tell agents to treat returned content as data. `apple-mail` has no way to send mail. |
  65. | The agent changes its own permissions | Fixed policy path, ownership and mode checks, plugin hooks, deny rules, and the Claude Code sandbox |
  66. | Input turns into code | Static JXA scripts that receive JSON, covered by fuzz tests; typed HTTP parameters for Paperless |
  67. | Supply chain | No third-party Go dependencies, SHA-pinned Actions, CodeQL, gosec, govulncheck, gitleaks and Scorecard; signed releases with SBOMs and build provenance |
  68. ## Protecting PII with AI agents
  69. Whatever an agent reads is sent to the model provider. You can reduce that:
  70. - Hide sensitive containers with `scopes.read.deny`, for example private folders, health lists or `tag:medical`.
  71. - Ask for less. `--fields`, `--limit` and `--max-chars` keep personal data out of the context, and the skills tell agents to use them.
  72. - Mask personal data before it reaches the model. [PasqualePillitteri/claude-privacy-tool](https://github.com/PasqualePillitteri/claude-privacy-tool) adds an offline masking hook to Claude Code, and [gregmos/PII-Shield](https://github.com/gregmos/PII-Shield) anonymises PII through an MCP server, a skill or a CLI.
  73. - Scan tool output with a Claude Code `PostToolUse` hook: [gitleaks/gitleaks](https://github.com/gitleaks/gitleaks) and [trufflesecurity/trufflehog](https://github.com/trufflesecurity/trufflehog) find secrets, and [data-privacy-stack/presidio](https://github.com/data-privacy-stack/presidio) (formerly microsoft/presidio) finds names, addresses, IBANs and phone numbers.
  74. - Keep real data out of bug reports. Redact output or use synthetic examples.
  75. ## Documentation
  76. - [Architecture decisions](docs/adr): stack, plugin distribution, permission model, macOS bridge
  77. - [Is a binary-enforced policy overkill?](docs/explanation/permission-research.md)
  78. - Each CLI repository has a tutorial, a how-to guide for permissions, a CLI reference and a page on its security model under `docs/`.
  79. ## Contributing
  80. Changes to shared behaviour start here. `scaffold/go` holds the shared Go packages (argument parsing, output, exit codes, policy, write gate, the JXA runner) with tests, fuzz targets and golden files. `scaffold/repo` holds the CI, release, documentation and plugin templates.
  81. ```sh
  82. make check # tests, lint, govulncheck, gitleaks, plugin validation
  83. python3 scaffold/render.py ../apple-mail-cli # render the scaffold into a CLI repository
  84. make drift # check that sibling repositories are up to date
  85. make install-smoke # install every plugin into a throwaway Claude config
  86. ```
  87. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
  88. ## Licence
  89. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.