Cueward

Local memory and automation for AI agents on macOS.

For agent setup, start with the included Cueward skill and installation/synchronization guide.

Cueward is a Unix-style CLI for agents that need structured access to native macOS data and actions. It reads Safari, Notes, Reminders, Calendar, Messages, Voice Memos, Stickies, Quick Notes, and Apple Shortcuts locally, then returns machine-friendly JSON that agents can actually use.

It is designed for agent workflows first:

• Native macOS reach: SQLite reads, AppleScript, EventKit, Vision OCR, and Shortcuts integration
• Agent-friendly output: structured JSON instead of chatty terminal prose
• Local-first privacy: native macOS APIs, no scraping proxy, no third-party data backend
• Practical automation: diagnose permissions with cueward doctor, then read, capture, search, and act

Common use cases:

• Give an agent a searchable local memory layer for what you read, saved, and wrote on macOS
• Build Shortcuts programmatically from CLI or spec files
• Read reminders and calendar events fast enough for background agents and daily briefings
• Capture Safari, Notes, screenshots, clipboard, and OCR results into a local index

Most first-time macOS integrations require system permissions before they work. If a command fails immediately on first use, check Privacy & Security settings first, grant the needed access, then run it again.

Install

Install the latest published release from crates.io:

cargo install cueward-cli --locked

To build from the local repo instead:

git clone https://github.com/Termdock-dev/cueward.git
cd cueward
cargo install --path crates/cli

Requires Rust 1.88+ (edition 2024). The CLI is macOS-only; the Windows adapter remains a reserved, unpublished stub. Running the Safari JavaScript behavior tests also requires Node.js on PATH.

What's New in 0.5.0

Cueward 0.5.0 includes the changes since the published 0.3.2 release:

• Scoped file browsing, reads, search, metadata, previews, Finder context and explicit iCloud download requests
• Guarded file management, including copy/duplicate, rename/move, bounded tree/package copy, batch rename, trash with verified backups and non-overwriting backup restoration
• App, window and Space discovery, AX inspection/actions, snapshot diffs and bounded background-operation workflows
• Modular Safari/CLI implementations and maintained agent skill references
• Rust 1.88 minimum; locked-session operation and generic background canvas/drag acceptance remain unverified. See the release notes for support boundaries.

macOS Permissions

Cueward reads local databases that require Full Disk Access:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Add your terminal app (Termdock, Terminal.app, iTerm2, WezTerm, etc.)

For Apple Notes, Reminders, and Calendar operations, also allow automation:

• System Settings > Privacy & Security > Automation > allow your terminal to control Notes, Reminders, and Calendar

files finder context needs Automation permission to control Finder. files finder reveal uses AppKit and explicitly requests Finder activation/selection.

Some integrations may additionally require:

• Accessibility / 輔助使用 for UI scripting style automations
• app-specific data access via Full Disk Access when reading container files

cueward window inspect requires Accessibility access for the terminal app running Cueward. Enable it in System Settings > Privacy & Security > Accessibility. If access is still denied after a terminal app update, remove the app from that list and add its current copy again; an old code-signing requirement can invalidate an enabled permission.

Calendar / Reminders Read Access

As of 0.3.0, Cueward prefers EventKit for reminders and calendar read commands because it is dramatically faster and more reliable than app scripting.

• cueward reminders list
• cueward reminders today
• cueward reminders list --due-tomorrow
• cueward calendar list
• cueward calendar today

For Reminders, allow the terminal app to read reminders when macOS prompts for access.

For Calendar, newer macOS versions may expose more than one permission level. Depending on your system language/version, you may see labels similar to:

• 取用 / 僅寫入
• 完整取用

If Calendar only has write-only access, Cueward will fall back to AppleScript for reads. That keeps commands working, but calendar list / calendar today can be much slower on some calendars. For the best performance, grant Calendar full access / 完整取用 to your terminal app.

Usage

Discover Commands

Use the built-in Clap help to explore the CLI surface:

# Top-level command list
cueward --help

# Subcommand-specific help
cueward notes --help
cueward reminders --help
cueward safari --help

# Alternative form
cueward help doctor
cueward help notes

This is the fastest way to see the current command tree and flags, especially as new integrations land.

Capture

Extract knowledge fragments from local sources:

# Everything from the last 24 hours
cueward capture --source all --since 24h

# Safari only, last 7 days
cueward capture --source safari --since 7d

# Apple Notes, last 3 hours
cueward capture --source notes --since 3h

Safari

Read current Safari tabs, not just browsing history:

# List all open tabs
cueward safari tabs

# Filter by Safari profile name parsed from window title
cueward safari tabs --profile Work

# Current active tab in the front window
cueward safari active

# Open a new tab
cueward safari open https://example.com

# Close current tab or a specific tab index in the front window
cueward safari close
cueward safari close --index 2

# Read current page text or a specific element
cueward safari read
cueward safari read --selector ".article-body"

# Read full HTML source
cueward safari source

# Execute JavaScript and keep JSON result types
cueward safari exec "document.title"
cueward safari exec "await Promise.resolve([1, 2])" --timeout 30
cueward safari exec --body "const x = await Promise.resolve(2); return x * 2;"
cueward safari click "#submit"
cueward safari fill "textarea" "hello from cueward"
cueward safari wait ".result" --timeout 30
cueward safari wait "#loading" --absent
cueward safari wait --text "Saved"
cueward safari wait --js "document.querySelector('#status')?.dataset.ready === 'true'"
cueward safari wait --url "/complete"
cueward safari wait --navigation

# Target a tab by index or URL/title match without changing the active tab
cueward safari read --tab "gemini.google.com" --profile Work
cueward safari exec "document.title" --tab 2
cueward safari source --tab "ChatGPT"
cueward safari click "#submit" --tab "Docs"

# Read visible elements, then use their refs in a batch
cueward safari inspect --tab "Docs" --limit 200
cueward safari batch --tab "Docs" --steps '[{"action":"click","ref":"<ref from inspect>"},{"action":"assert","js":"document.querySelector(\"#menu\").getAttribute(\"aria-expanded\") === \"true\""}]'

# A batch also accepts selector or visible text targets
cueward safari batch --steps '[{"action":"fill","selector":"#query","value":"hello"},{"action":"key","selector":"#query","key":"Enter"}]'

# Scroll the page
cueward safari scroll down
cueward safari scroll up --amount 1000
cueward safari scroll top
cueward safari scroll bottom --profile Work

# Close multiple tabs by profile or URL pattern
cueward safari close-tabs --profile Work --url "gemini.google.com"
cueward safari close-tabs --profile Work  # close all tabs in profile

# List bookmark/folder items from the Safari bookmarks root
cueward safari bookmarks list

# Scope bookmarks to a specific Safari profile folder
cueward safari bookmarks list --profile Work

# Traverse nested bookmark folders inside a profile
cueward safari bookmarks list --profile Work --folder "Projects/AI Tools"

# Folder paths use "/" as the separator; folder titles containing "/" are not supported
# in this first version

# Search bookmarks recursively from the root or a profile folder
cueward safari bookmarks search "claude"
cueward safari bookmarks search "claude" --profile Work --folder "Projects"

# Add a bookmark into a nested folder inside a profile
cueward safari bookmarks add --title "Claude" --url "https://claude.ai" --profile Work --folder "Projects/AI Tools"

# Delete by exact title + URL within a profile folder
cueward safari bookmarks delete --title "Claude" --url "https://claude.ai" --profile Work --folder "Projects/AI Tools"

exec evaluates one JavaScript expression and returns a JSON result with a value_type; undefined has a null result with type undefined. Expressions may use await. Use --body and an explicit return for multiple statements. wait --js and batch assert.js accept synchronous expressions.

inspect refs remain valid until the next inspect, page navigation, or element removal. batch accepts up to 100 steps. Each action targets one ref, CSS selector, or visible text. Actions are click, fill (value), key (key, optional ctrl/alt/meta/shift), select (value), check (checked), scroll_into_view, and assert (js or a target). A failed step reports its index and exits with an error. Open shadow roots and same-origin iframes are searched; closed shadow roots and cross-origin iframes cannot be accessed through page JavaScript.

Click and key events sent through JavaScript have isTrusted: false. They can reach page event handlers but cannot replace a trusted user gesture or native keyboard editing. Use a following assert or wait condition to verify the page changed as expected.

Safari diagnostics

# The first call starts capture in that tab; repeat it after reproducing the issue
cueward safari console --tab "example.com" --level error
cueward safari network --tab "example.com"
cueward safari network get 2 --tab "example.com"

Console capture includes log, info, warn, error, and debug. Network capture covers fetch and XMLHttpRequest; summaries include URL, method, status, and duration. network get adds headers and up to 16 KiB of text response. Capture starts when either diagnostics command first runs in a page and ends when that page navigates or closes. Earlier console messages, requests, and browser-level traffic are unavailable. Each buffer keeps the latest 300 entries.

Safari AI

Control web-based AI providers (Gemini, ChatGPT) via Safari automation. The ChatGPT effort option uses the composer's slider before sending a prompt.

# Send a prompt (general chat)
cueward safari ai --provider gemini prompt --prompt "explain quantum computing"
cueward safari ai --provider chatgpt prompt --prompt "explain quantum computing" --timeout 900
cueward safari ai --provider chatgpt prompt --prompt "explain quantum computing" --effort pro

# Switch to a specific mode first
cueward safari ai --provider gemini prompt --prompt "a cat on a keyboard" --mode image

# Deep Research with auto-confirm
cueward safari ai --provider gemini prompt --prompt "台灣 AI 產業分析" --mode deep-research --auto-confirm

# Switch mode only (no prompt)
cueward safari ai --provider gemini mode deep-research

# List conversations from sidebar
cueward safari ai --provider gemini list

# Read a conversation's text content (reports, chat history)
cueward safari ai --provider gemini read https://gemini.google.com/app/abc123

# Poll an in-progress Deep Research
cueward safari ai --provider gemini poll --timeout 300

# Save AI-generated images as PNG
cueward safari ai --provider gemini save-images https://gemini.google.com/app/abc123 --output ~/Downloads

# Download video/music via browser (triggers Safari native download)
cueward safari ai --provider gemini save-media https://gemini.google.com/app/abc123

# Use a specific Safari profile
cueward safari ai --provider gemini --profile Work list

Supported Gemini modes: deep-research, image, video, music.

ChatGPT --effort accepts a number within the slider's current ARIA range or pro for its maximum. It applies to normal prompts and checks the slider value before sending.

Reddit

Read Reddit via public old.reddit.com/*.json endpoints. These commands do not use Safari automation.

# Read a subreddit feed
cueward reddit feed rust
cueward reddit feed r/rust --limit 50

# Read a post plus top-level comments
cueward reddit post https://www.reddit.com/r/rust/comments/abc123/example_title/

# Search posts globally or inside one subreddit
cueward reddit search "async rust"
cueward reddit search "async rust" --subreddit r/rust --limit 25

Repeated scans may return status metadata such as fresh, unchanged, skipped, warning, or deleted, with data omitted when the target is skipped or confirmed deleted.

Outputs JSON to stdout:

[
  {
    "source": "safari",
    "timestamp": "2026-04-07T03:14:16Z",
    "content": "Rust Concurrency Patterns - Blog",
    "url": "https://example.com/rust-concurrency",
    "title": "Rust Concurrency Patterns - Blog"
  },
  {
    "source": "notes",
    "timestamp": "2026-04-07T01:16:16Z",
    "content": "Meeting notes from product sync...",
    "title": "Product Sync 2026-04-07",
    "metadata": {
      "folder": "Work"
    }
  }
]

Triage

Auto-tag and index captured cues:

cueward triage

Reads from ~/.cueward/inbox/, applies keyword-based auto-tagging, and writes to a local BM25 index.

Configure auto-tagging in ~/.cueward/tags.toml:

[rust]
keywords = ["Rust", "cargo", "crate", "rustc"]

[ai]
keywords = ["AI", "LLM", "ChatGPT", "Claude", "GPT"]

[finance]
keywords = ["stock", "ETF", "investment"]

Search

Query the local index:

cueward search "rust concurrency" --limit 5

Send

Create a digest note in Apple Notes and optionally trigger a macOS notification:

# Create a note
cueward send --title "Daily Digest" --body "Today's summary..." --folder Cueward

# With notification
cueward send --title "Daily Digest" --body "Summary" --notify

# Pipe from capture
cueward capture --source all --since 24h | cueward send --title "2026-04-07 Digest"

Plan

Create a reminder in Apple Reminders:

cueward plan --title "Review PR" --notes "Check bot comments" --list Cueward

Reminders

Read and manage Apple Reminders:

# List all reminders
cueward reminders list

# Filter by reminders list
cueward reminders list --list Work

# Reminders due today
cueward reminders today

# Create a reminder
cueward reminders create --title "Review PR" --due "2026-04-22 10:00" --list Cueward --notes "Check review threads"

# Update a reminder by id or title
cueward reminders update --id x-apple-reminder://123 --new-title "Review PR #114" --priority 5
cueward reminders update --title "Review PR" --list Archive

# Mark complete
cueward reminders complete --title "Review PR"

# Delete
cueward reminders delete --title "Review PR"

Outputs JSON with title, notes, due_date, completed, and list_name.

OCR

Extract text from images or PDFs via Apple Vision Framework:

cueward ocr ~/Desktop/screenshot.png
cueward ocr ~/Documents/paper.pdf

Supports PNG, JPG, PDF. Languages: zh-Hant, zh-Hans, en-US, ja.

Notes Management

Update, delete, or move Apple Notes:

# Create a note
cueward notes create --title "Daily Digest" --body "Summary..." --folder Cueward

# Update a note's body
cueward notes update --title "Note Title" --body "New content" --folder Cueward

# Delete a note
cueward notes delete --title "Note Title" --folder Cueward

# Move between folders
cueward notes move --title "Note Title" --from Cueward --to Archive

Calendar

Query and manage Apple Calendar events:

# Today's events
cueward calendar today

# Events in a time range
cueward calendar list --from "2026-04-11 09:00" --to "2026-04-11 18:00"

# Filter by calendar
cueward calendar list --calendar Work

# Create an event
cueward calendar create --title "Team Sync" --start "2026-04-12 14:00" --end "2026-04-12 15:00" --calendar Work --location "Google Meet" --notes "Weekly sync"

# Delete an event (matches by title + start time)
cueward calendar delete --title "Team Sync" --start "2026-04-12 14:00" --calendar Work

# Update an event
cueward calendar update --title "Team Sync" --calendar Work --new-start "2026-04-12 14:30" --new-end "2026-04-12 15:30"

Datetime format: ISO 8601 (2026-04-11T14:00:00) or YYYY-MM-DD HH:MM.

Shortcuts

Create and manage Apple Shortcuts, including declarative spec workflows:

# List shortcuts
cueward shortcuts list

# Create a blank shortcut
cueward shortcuts create "Clean URL Share"

# Show one shortcut as a high-level YAML-like spec
cueward shortcuts show --name "Clean URL Share"

# Set accepted input and attach Share Sheet surface
cueward shortcuts input-type --name "Clean URL Share" url
cueward shortcuts surface --name "Clean URL Share" share-sheet
cueward shortcuts surface --name "Clean URL Share" library-root

# Append actions incrementally
cueward shortcuts add-text --name "Clean URL Share" --value "hello"
cueward shortcuts add-get-urls --name "Clean URL Share" --from extension-input --output urls
cueward shortcuts add-get-text --name "Clean URL Share" --from urls --output url_text
cueward shortcuts add-replace-text --name "Clean URL Share" --from text --find "hello" --replace "world"
cueward shortcuts add-copy-to-clipboard --name "Clean URL Share" --from text_2
cueward shortcuts add-share --name "Clean URL Share" --from text_2

# Control flow
cueward shortcuts add-if --name "Clean URL Share" --input text --value world --then-actions then.yaml
cueward shortcuts add-repeat --name "Clean URL Share" --input urls --body-actions repeat.yaml

# Spec-based workflow
cueward shortcuts validate-spec clean-url-share.yaml
cueward shortcuts apply clean-url-share.yaml
cueward shortcuts export-spec --name "Clean URL Share"

# Rename, move, and run
cueward shortcuts rename --name "Clean URL Share" "Clean URL Share v2"
cueward shortcuts move --name "Clean URL Share v2" "Utilities"
cueward shortcuts run --name "Clean URL Share v2"

Selector-based commands generally accept either --name or --id.

Screenshot

Capture a screenshot, optionally with OCR:

# Capture main screen
cueward screenshot

# With OCR text extraction
cueward screenshot --ocr

# Specific display (1=main, 2=secondary, 3=third)
cueward screenshot --display 2

# List capturable windows
cueward screenshot windows

# Capture a specific window
cueward screenshot window --id 12345

# Capture a specific window with OCR
cueward screenshot window --id 12345 --ocr

# Custom output path
cueward screenshot --output ~/Desktop/shot.png --ocr

Window inspection and actions (PoC)

For window discovery and image snapshots across Spaces, see Window discovery and snapshots. For background Unicode input, keys, scrolling, clicks, drags, and dispatch readiness checks, see Background input. Inspect a window, including another Space when the app exposes the relevant Accessibility elements:

# Find the window id, including other Spaces
cueward window list --all-spaces

# Read its Accessibility element tree
cueward window inspect --id 12345

# Limit the tree and include a window screenshot with OCR
cueward window inspect --id 12345 --limit 100 --depth 6 --ocr

# Explore a group using an element ref from the current inspection
cueward window inspect --id 12345 --root 0.1 --depth 2

# Explore the app menu using its main window as context
cueward window inspect --id 12345 --surface menu

# Use a node's target token from the inspection result
cueward window press --target '<target token>'
cueward window set-value --target '<text field target token>' --value 'Draft text'

These commands require the Swift toolchain (swift on PATH), Accessibility access, and permission to read window metadata. Inspection returns window identity, element roles, names, values, actions, element refs, child counts, and available bounds. Password fields omit values and action targets. truncated reports when the node or depth limit omitted elements. See Exploring app interfaces for subtree navigation, menus, sheets, coordinates, and result verification.

Actionable nodes include a target token valid for five minutes. Actions recheck the window's process, title, and bounds, then the element's path, attributes, and ancestors. Changed or ambiguous targets return an error and require a fresh inspection. These checks use observable attributes; they cannot distinguish a replacement with identical attributes at the same location. Tokens are snapshot references, not authorization credentials.

press invokes AXPress and reports sent_unverified: the app accepted the API call, but Cueward cannot confirm the intended effect. set-value supports editable text fields and areas; confirmed means their AXValue matched the requested text on readback. It does not confirm saving or form submission. An unconfirmed result or timeout requires inspecting the current state before retrying.

Cueward sends no global mouse or keyboard events and does not activate the app. foreground_changed compares the frontmost app before and after the action; an app may still activate itself as a side effect. Canvas-only apps and elements without the required Accessibility action are outside this PoC.

Waiting for UI changes

Use cueward window wait --target '<snapshot input_target>' --condition enabled --role AXButton --name Continue to observe a condition without replaying an action. Exact value, presence, absence, and window-closure checks are also available. See window waits for bounded traversal, timeout, ambiguity, and recovery semantics.

Application discovery

Use cueward app list to discover running apps. cueward app launch --bundle org.example.Editor requests a background launch or returns an existing instance without reopening it. Discover the resulting windows before sending input. See application discovery for launch-result semantics and limitations.

Use cueward app inspect --pid 123 to discover an app's AX roots, including menus without a document window and exposed system dialogs. Inspect a returned root with --root menu or --root w0, then use app press or app set-value with a fresh node target. See application interface exploration for process binding, background guards, and limitations.

File browsing, search and reading

Use cueward files list --root /absolute/directory to browse one level, files info to inspect metadata, and files read --root /absolute/directory --path relative/file.txt to read a bounded byte or UTF-8 line range. Use cueward files search --root /absolute/directory --name report --kind file --max-depth 3 to find names and metadata within an explicit depth, with size/date filters and query-bound pagination. See filesystem search for budgets and completeness.

Use cueward files spotlight --root /absolute/directory --text invoice --max-depth 3 for indexed content candidates. Index coverage is unknown and current contents are not verified; zero results do not prove absence. See Spotlight search for budgets and source/completion semantics.

Use files preview pdf/image/thumbnail --root /absolute/directory --path relative/file for selected PDF page text/images, first-frame image information/preview, or a Quick Look content thumbnail. OCR is explicit with --ocr on PDF/image; thumbnail success never means full-text extraction. See file previews for budgets, provenance, cache and format support.

Use files mkdir, files copy and files duplicate --name for authorized no-overwrite creation/copy/sibling duplication with fresh source/parent revisions. Copy/duplicate support files, bounded directory/package trees, opaque aliases and symlink references without target traversal. Different-volume copies use destination-local private staging. Preserve failed staging/evidence and inspect with files receipt before any new decision. See file mutations.

Use files rename/move without overwrite. Same-volume relocation preserves the object inode; different-volume move verifies an independent destination then retains the original privately, never permanently deleting it. Links require explicit --link-itself and reference text is never repaired/followed. Dry-run observes only; inspect saved evidence with files relocation receipt. See relocation and link selection.

Use files copy-tree plan to inspect a bounded recursive directory copy proposal with source/parent revision guards. It retains exact mapped destinations, unsupported nodes and namespace blockers, but never copies, allocates mutation receipts or supplies an execution token. Authorized files copy-tree execute constructs and verifies a bounded ordinary tree privately before one guarded no-overwrite publication; files copy-tree receipt reads its saved evidence. This execution source capability was merged in PR #59 and has a stricter 64-entry limit. Known package directories can be traversed with explicit --include-packages on plan/execute when installed, retaining all existing bounds and metadata refusals; this package opt-in was merged in PR #63. See package copying. Check installed help. See recursive copy plans and tree execution.

Use files rename-batch plan --root --entry '<JSON>' with explicit source/name/revision proposals to inspect a batch without renaming. The result retains item errors, existing targets and cross-entry collisions/dependencies; no execution token or automatic ordering is produced. See batch rename plans. Authorized independent batches use files rename-batch execute with the same explicit entries and fresh guards; it replans remaining items, stops on any failure, and never retries or rolls back. Read aggregate evidence with files rename-batch receipt and per-item evidence with files relocation receipt. See batch execution. New per-entry "link_itself":true selects only the symlink object and permits mixed link/ordinary batches; it was merged in PR #65 and has no global batch flag. See batch link rename and check installed help.

Use files trash plan --root --path --expected-version to inspect one selected entry before deciding a removal, with directory/link scope and metadata warnings. It never moves/deletes anything or provides an execution token. Separately authorized files trash execute --confirm verifies and retains a private verified object backup, quarantines the original within guarded scope, then uses native system trash and saves the actual result; files trash receipt reads saved evidence. Execution was merged in PR #61. Separately authorized files trash restore copies a completed receipt’s verified backup to the recorded original path, without overwrite or removal of Trash/backup; restore-receipt reads its new receipt. Backup restoration was merged in PR #62; check installed help. Broader recovery and permanent deletion are not supported. See trash proposals, verified trash execution and backup restoration.

files tags read/add/remove/receipt edits requested names on supported existing tag sets while preserving unselected names/colors and saving the original attribute. Revision checks are not atomic value CAS; do not promise isolation from last-instant Finder/provider edits. See file tags.

Use files cloud status --root /absolute/directory --path relative/file for per-field iCloud state. files cloud download explicitly submits a version-guarded iCloud file download; submission does not verify completion, and other provider state remains unknown. See cloud state and downloads.

Use files metadata --root /absolute/directory --path relative/file.txt for native UTType, Finder tags and package/alias flags with per-field availability; see resource metadata. Sorting, hidden names, versioned pagination, explicit encoding, and hex output are available. See file operations for root scope, symlink handling, implicit-download prevention, errors, deadlines, and remaining Finder capabilities.

Use cueward files finder context --root /absolute/directory to inspect scoped Finder location/selection without requesting activation. files finder reveal --root /absolute/directory --path relative/file.txt explicitly requests Finder activation and selection, reporting sent_unverified rather than UI completion. See Finder context and reveal for scope, locks, deadlines and verification.

Existing macOS Spaces

cueward space list
cueward space window --id 12345
cueward space move-window --target '<snapshot input_target>' --space 7

Move a specifically observed background window to an existing inactive user Space, then verify membership and take a fresh snapshot. See Space management for routing requirements, result semantics, and limitations.

Clipboard

Read and write the system clipboard:

# Read clipboard (text or image)
cueward clipboard get

# Save clipboard image to a specific path
cueward clipboard get --save-image ~/Desktop/clip.png

# Write text to clipboard
cueward clipboard set "Hello from cueward"

Text content returns JSON with "type": "text". Image content is saved as PNG and returns "type": "image" with the file path.

Doctor

Run a read-only macOS preflight before using integrations that depend on permissions:

# Human-readable summary
cueward doctor

# Machine-readable report
cueward doctor --json

# Opt-in Safari JavaScript probe
cueward doctor --live-safari
cueward doctor --json --live-safari

doctor checks:

• filesystem / Full Disk Access access to the current local data sources
• Apple Events / Automation access for Notes, Reminders, Calendar, and Safari
• an optional Safari JavaScript probe that reuses the normal Safari guard path

The JSON output includes stable check IDs such as fda.messages.chat_db, automation.notes, and live.safari.js.

Quick Notes

List, update, archive, and delete system Quick Notes (快速備忘錄):

# List all Quick Notes
cueward quick-notes list

# Update a Quick Note's body
cueward quick-notes update --title "Note Title" --body "New content"

# Delete a Quick Note
cueward quick-notes delete --title "Note Title"

# Archive a Quick Note into a regular note, then remove it from Quick Notes
cueward quick-notes archive --title "Note Title" --to Archive

# Create a note in the Quick Notes folder
cueward quick-notes create --title "Title" --body "Content"

Quick Notes are identified by the system ZISSYSTEMPAPER flag — notes created via the macOS Quick Note gesture (hot corner, Apple Pencil, etc.). list, update, and delete operate on these system-tagged notes regardless of which folder they reside in. create places a regular note in the "Quick Notes" folder but does not mark it as a system Quick Note.

archive is the cleanup workflow for real Quick Notes: it copies the note into a regular destination folder, waits for the new note to appear, and deletes the original Quick Note so it disappears from the Quick Notes smart view. This preserves link URLs, but Apple Notes rich-link cards may be flattened into normal links in the archived copy.

Voice Memos

Read Voice Memos metadata from the local shared database:

# List all voice memos
cueward voice-memos list

# Read one voice memo by id
cueward voice-memos read --id F45D4751-183C-4032-99F7-F1FE1F541BA2

Outputs JSON with id, title, duration_seconds, timestamp, and path.

Stickies

Manage Stickies notes from the desktop:

# List notes
cueward stickies list

# Create a note
cueward stickies create --title "Temp" --body "Remember this"

# Update a note
cueward stickies update --id sticky-1 --title "Updated title"

# Delete a note
cueward stickies delete --id sticky-1

Use cueward stickies --help to inspect the geometry and color flags for create / update.

Agent Integration

Cueward outputs structured JSON — it does not call any LLM. The LLM layer is your Agent's responsibility.

Pipe to an Agent

# Claude Code
cueward capture --source all --since 24h | claude --print "Summarize my knowledge intake today"

# Gemini CLI
cueward capture --source all --since 24h | gemini "Group these by topic and highlight action items"

As a Skill

The maintained skill lives in skills/cueward-agent. Repo discovery links in .agents/skills/ and .claude/skills/ point to that same source for local Codex and Claude Code sessions. It routes among local data, Safari DOM/diagnostics, app/window/Space operations, Shortcuts, and bounded file reads when the installed CLI supports them.

For use in other projects, see installation and synchronization, including verified backups before updating an existing copy. Updating the skill does not update cueward: check command -v cueward and subcommand --help before using newly documented commands. The scoped file commands merged starting with PR #44 are included in 0.5.0; older installed versions may not expose them.

Architecture

crates/
├── core/               Cue types, adapter trait, inbox/state/index, shortcuts spec model
├── cli/
│   ├── main.rs         CLI entrypoint
│   └── commands/       Per-command clap enums, dispatch, and parse tests
├── adapter-macos/
│   ├── applescript.rs      Shared AppleScript helpers
│   ├── bookmarks/          Safari bookmarks CRUD + plist tree operations
│   ├── calendar.rs         Apple Calendar CRUD + AppleScript fallback
│   ├── calendar_eventkit.rs EventKit-backed calendar reads
│   ├── clipboard.rs        Clipboard read / write
│   ├── doctor/             Full Disk Access / Automation diagnostics
│   ├── messages.rs         iMessage capture
│   ├── notes/              Apple Notes CRUD, capture, DB reads, attachments
│   ├── ocr.rs              Vision OCR
│   ├── plan.rs             Reminder creation shortcut command
│   ├── quick_notes.rs      Quick Notes workflows
│   ├── reddit/             Reddit JSON API reads and scan-state integration
│   ├── reminders.rs        Apple Reminders read / write + AppleScript fallback
│   ├── reminders/eventkit.rs EventKit-backed reminder reads
│   ├── safari/             Tabs, history, AI providers, social feeds
│   ├── safari_guard.rs     Shared Safari rate limit + file lock guard
│   ├── scan_state.rs       Shared polling / target state tracking
│   ├── screenshot/         Screen/window capture + OCR integration
│   ├── shortcuts/          Shortcuts DB compiler, installer, and tests
│   ├── stickies/           Stickies CRUD, geometry, color, state
│   └── voice_memos.rs      Voice Memos metadata reads
└── adapter-windows/    Reserved for future cross-platform support

• Core Engine + Adapter Pattern: Platform-specific code is isolated in adapters. Core logic is platform-agnostic.
• Native First: Direct SQLite reads, AppleScript, EventKit, and Vision Framework. No cloud APIs and no browser-driving frameworks in the normal data path.
• Privacy: All data extraction happens locally. Nothing leaves your machine.

Data Storage

~/.cueward/
├── inbox/            Captured cues awaiting triage
├── processed/        Triaged cues moved out of inbox
├── index/            Tantivy BM25 search index and lock files
├── cache/
│   ├── ocr/          OCR result cache keyed by SHA256
│   ├── screenshots/  Screenshot captures
│   └── clipboard/    Clipboard image captures
├── state.json        High watermark timestamps and scan target state
├── tags.toml         Auto-tagging keyword rules
└── lock.json         Safari automation lock / rate-limit coordination

Additional app- or tool-specific scratch directories may appear under ~/.cueward/ over time, but the paths above are the stable managed data layout that Cueward itself depends on.

License

MIT