Skip to content

Replace memo-based Apple Notes skill with native osascript workflow - #6480

Closed
lishix520 wants to merge 1 commit into
NousResearch:mainfrom
lishix520:codex/native-apple-notes-skill
Closed

Replace memo-based Apple Notes skill with native osascript workflow#6480
lishix520 wants to merge 1 commit into
NousResearch:mainfrom
lishix520:codex/native-apple-notes-skill

Conversation

@lishix520

Copy link
Copy Markdown

This PR replaces the built-in Apple Notes skill guidance with a native osascript workflow on macOS.

Why make this change:

  • much lower user friction
  • no third-party Apple Notes CLI like memo
  • no brew tap / brew install step
  • better fit for agent automation than interactive terminal flows
  • simpler for users who already have Notes.app and just want it to work

From a user-experience standpoint, this is the main improvement: the current skill asks the user to install and trust an extra wrapper CLI before the agent can do anything useful. The native osascript path removes that friction and gives the agent a single built-in access path it can reuse across sessions.

What this updated skill covers:

  • read notes
  • search notes
  • create notes
  • append/update existing notes
  • create folders
  • move notes
  • organize uncategorized notes
  • write cleaner structured content into Notes

It also keeps the guidance more agent-oriented by preferring append over overwrite, requiring clarification on ambiguity, and documenting practical organization workflows instead of relying on interactive prompts.

The only system requirement is standard macOS Automation permission for Notes, which users already need for any native Apple Notes automation.

I also opened an issue for discussion here: #6478

@lishix520
lishix520 force-pushed the codex/native-apple-notes-skill branch from dc2cd45 to f6d214d Compare April 13, 2026 06:33
@alt-glitch alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have tool/skills Skills system (list, view, manage) labels Apr 30, 2026

@teknium1 teknium1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for replacing the extra memo dependency with a native macOS path. Current main still requires memo in skills/apple/apple-notes/SKILL.md:13, so the premise is valid.

Problems

  • skills/apple/apple-notes/SKILL.md:3 is 119 characters; modernized skill descriptions must be one sentence, ≤60 characters, and end with a period (AGENTS.md:888-900).
  • skills/apple/apple-notes/SKILL.md:18 makes osascript the prose interaction surface. Skills must name the Hermes terminal tool for shell work (AGENTS.md:902-914).
  • The promised append/update, folder creation, and move workflows have no executable procedure: skills/apple/apple-notes/SKILL.md:104-120 contains only advice. Add validated, noninteractive examples/helper scripts or narrow the stated coverage.
  • This modernization retains author: Hermes Agent and adds no skill test, contrary to AGENTS.md:926-950.

Suggested changes

  • Update the metadata and add a focused tests/skills/test_apple_notes_skill.py.
  • Provide safely parameterized AppleScript workflows for each claimed mutation, validated on macOS Notes.

Automated hermes-sweeper review.

Comment thread skills/apple/apple-notes/SKILL.md Outdated
@@ -1,7 +1,7 @@
---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS (create, view, search, edit).
version: 1.0.0
description: Manage Apple Notes natively on macOS via osascript and Notes automation (read, search, create, append, organize, move).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description is 119 characters. Modernized skills require one sentence of at most 60 characters ending with a period (AGENTS.md:888-900); please shorten it before merge.

Comment thread skills/apple/apple-notes/SKILL.md Outdated
---

# Apple Notes

Use `memo` to manage Apple Notes directly from the terminal. Notes sync across all Apple devices via iCloud.
Use Apple Notes natively through `osascript` and macOS Notes automation.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please name Hermes' terminal tool as the interaction surface here (for example, “Use terminal to run macOS osascript commands”). The skill standards prohibit presenting a shell utility as the headline tool in prose (AGENTS.md:902-914).

Comment thread skills/apple/apple-notes/SKILL.md Outdated
- Choose the correct folder if known
- Use a clear title and readable structure

### Append or Update

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR claims append/update support, but this section supplies only advice. Add a safely parameterized, macOS-validated command or helper script for appending to an identified note; do the same for the claimed folder-create and move workflows.

@teknium1 teknium1 added sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users labels Jul 12, 2026
@lishix520

Copy link
Copy Markdown
Author

Pushed a5a2c46 addressing the review. All four points + suggested changes:

1. description ≤60 chars (SKILL.md:3) — now Read, search, create, and organize Apple Notes on macOS. (56 chars, one sentence, ends with a period).

2. terminal as the interaction surface (SKILL.md:18) — prose now names the Hermes terminal tool and routes through a helper script; osascript is no longer the headline tool.

3. Executable procedures for append / folder / move (SKILL.md:104-120) — added scripts/apple_notes.py, a parameterized, noninteractive helper exposing list-folders, list-notes, search, read, create, append, create-folder, move. SKILL.md references it by path with copy-pasteable terminal invocations. All mutations were validated against a live Notes.app scratch folder (create → append → read → list-notes → search → move → read-in-dest), then cleaned up.

4. author + skill test (AGENTS.md:926-950) — author now credits the human contributor first (Li shixiong (lishix520); Hermes Agent); added tests/skills/test_apple_notes_skill.py — 21 tests covering metadata compliance, AppleScript string building/escaping, and CLI dispatch (stdlib + pytest + unittest.mock, no network).

Suggested changes — metadata updated; focused test added at tests/skills/test_apple_notes_skill.py; safely parameterized AppleScript workflows provided for each claimed mutation and validated on macOS Notes.

One bug found and fixed during live validation: list-notes originally used a one-liner every note of first folder whose name is F, which mis-parses in AppleScript (whose binds to the note, not the folder) and silently returns empty. Rewrote it to use a tell block; covered by a regression test.

@lishix520
lishix520 force-pushed the codex/native-apple-notes-skill branch from a5a2c46 to 9828a77 Compare July 13, 2026 02:39
Replace the third-party `memo` CLI dependency with a native macOS
`osascript` path driven through a helper script, so the skill works
without `brew tap` / `brew install memo`.

- SKILL.md: rewritten to the modern section order; description <=60 chars,
  one sentence ending with a period (AGENTS.md #1); prose names the Hermes
  `terminal` tool as the interaction surface, not osascript (AGENTS.md #2);
  `author` credits the human contributor first (AGENTS.md #4)
- scripts/apple_notes.py: parameterized, noninteractive helper exposing
  list-folders, list-notes, search, read, create, append, create-folder,
  move. AppleScript string building is separated from osascript execution
  so it is unit-testable (AGENTS.md #6)
- tests/skills/test_apple_notes_skill.py: metadata compliance, AppleScript
  string building/escaping, and CLI dispatch (stdlib + pytest + unittest.mock)
- all mutations validated against a live Notes.app scratch folder
@lishix520
lishix520 force-pushed the codex/native-apple-notes-skill branch from 9828a77 to 1bc9b2d Compare July 13, 2026 02:39
@lishix520 lishix520 closed this by deleting the head repository Jul 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low — cosmetic, nice to have sweeper:blast-contained Sweeper blast radius: contained — one narrow path / opt-in / few users sweeper:risk-compatibility Sweeper risk: may break existing users, config, migrations, defaults, or upgrades tool/skills Skills system (list, view, manage) type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants