Apple Notes

Codex skill, Claude Code skill, and CLI for reading/writing Apple Notes via AppleScript.

Codex usage

Codex skills are loaded from $CODEX_HOME/skills (usually ~/.codex/skills) and require a SKILL.md. This repo includes SKILL.md and agents/openai.yaml.

# Install as a local skill
mkdir -p ~/.codex/skills
ln -s /path/to/apple-notes-skill ~/.codex/skills/apple-notes-skill

Restart Codex after installing so the new skill is detected.

Invoke it in prompts as $apple-notes, for example:

$apple-notes Assign priorities to items in my Project Backlog note

Claude usage

Claude Code skills are loaded from ~/.claude/skills and require a SKILL.md. This repo includes SKILL.md with Claude Code-compatible metadata.

# Install as a local skill
mkdir -p ~/.claude/skills
ln -s /path/to/apple-notes-skill ~/.claude/skills/apple-notes-skill

Invoke it with the /apple-notes slash command, for example:

/apple-notes Assign priorities to items in my Project Backlog note

CLI usage

# Preferred direct commands
./notes.py list
./notes.py read "Note Name" -
./notes.py write "Note Name" /tmp/note.html

# Read to stdout (wrapper)
./copy-note.sh "Note Name"

# Read to file (wrapper)
./copy-note.sh "Note Name" /tmp/note.html

# Write from file (wrapper)
./update-note.sh "Note Name" /tmp/note.html

# Write from stdin (wrapper)
cat note.html | ./update-note.sh "Note Name" -

# Pipe: read → transform → write
./notes.py read "Note" - | sed 's/Old/New/g' | ./notes.py write "Note" -

What the Agent Gets

The skill and agent docs give the agent:

• Direct notes.py commands for read/write/list
• Streaming patterns (stdin/stdout with -)
• Important caveats (lossy body property, exact-name matching)

How It Works

Uses AppleScript's body property to read/write note HTML directly. This approach is:

• Fast — direct property access
• Headless — runs without user interaction
• Scriptable — supports stdin/stdout piping

Trade-off: The AppleScript body property is lossy — checkbox state and some heading semantics are not preserved on round-trip.

Requirements

• macOS with Notes.app
• Python 3 (stdlib only, no pip dependencies)

Troubleshooting

• If you see Connection Invalid error for service com.apple.hiservices-xpcservice or parser-like errors such as Expected class name but found identifier (-2741), retry once after opening Notes.app.
• notes.py now retries transient Notes automation failures automatically with short backoff before surfacing an error.