# Dottie Agent API

> Dottie is a local macOS AI assistant. The Agent API runs on 127.0.0.1:1317 and provides SSE streaming chat, tool calling, personal data access, and agent management. The API provides the personal context needed to build truly personal AI assistants — combining access to macOS system data with local AI inference, streaming chat, and tool calling.

## Authentication

Every request to the Dottie API (except the health check) must include a Bearer token in the Authorization header. Dottie generates this token automatically on first launch and stores it at ~/.dottie/agent_token. This token ensures that only applications running on your machine can access your personal data — it is never sent over the network and never leaves localhost.

```
Authorization: Bearer <token>
```

## Base URL

```
http://127.0.0.1:1317
```

## Endpoints

### Health

The health endpoint lets you verify that the Dottie agent service is running and ready to accept requests. This is the only endpoint that does not require authentication, making it ideal for connection checks, monitoring scripts, and startup probes.

- GET /health — Returns the current status of the agent service, including whether the agent has finished initializing, which language model is loaded, and how many tools are available. Use this to verify the service is ready before making other API calls.
  - Response: { status, initialized, model, toolCount }

### Chat

The chat endpoint is the primary way to interact with Dottie. It accepts a conversation history and streams back a response in real time using Server-Sent Events (SSE). The agent can think, generate text, call tools (like searching your contacts or checking your calendar), and return results — all within a single streaming response.

- POST /v1/chat/completions — Send a conversation to the agent and receive a streaming response. The response is delivered as Server-Sent Events with the following event types: "thinking" (the agent is reasoning), "text_delta" (a chunk of the response text), "tool_start" (the agent is calling a tool), "tool_result" (the tool returned data), "done" (the response is complete), and "error" (something went wrong). The stream terminates with data: [DONE].
  - Body: { messages: [{role, content}], model: string }
  - messages (array, required): The conversation history. Each message has a "role" (either "user" or "assistant") and a "content" string. Send the full conversation history with every request — the agent is stateless.
  - model (string, required): The model identifier to use. Use /health to see which model is loaded.

### Goals

Goals represent high-level objectives that the agent tracks over time. When a user tells Dottie something like "help me exercise more" or "I want to learn Spanish," the agent creates a goal and periodically checks in on progress.

- GET /v1/goals — Retrieve all goals the agent is currently tracking. Each goal includes an ID, a description of the objective, and metadata about when it was created. Useful for building a goals dashboard.
- DELETE /v1/goals/:id — Permanently remove a goal by its ID. The agent will stop tracking progress and will no longer reference this goal in conversations or heartbeat check-ins.

### Triggers

Triggers are event-driven automations that the agent monitors. For example, a trigger might watch for new emails from a specific sender, or fire when a calendar event is about to start. When conditions are met, the agent takes an action like sending a notification or running a prompt.

- GET /v1/triggers — List all configured triggers, including their conditions, actions, and whether they are currently enabled.
- PATCH /v1/triggers/:id — Enable or disable a trigger without deleting it. Useful for temporarily pausing an automation without losing the configuration.
  - Body: { enabled: boolean }
- DELETE /v1/triggers/:id — Permanently delete a trigger and stop monitoring its conditions.

### Memory

The memory system is the agent's key-value store for facts it learns during conversations. When Dottie discovers something important about you — your preferred name, your work schedule, your dietary restrictions — it stores that as a memory entry. These memories persist across sessions and help the agent give more personalized, context-aware responses.

- GET /v1/memory — Retrieve all memory entries the agent has stored. Each entry has a key (a short label like "preferred_name") and a value (the information itself).
- DELETE /v1/memory/:key — Delete a specific memory entry by its key. Use this if the agent has stored something incorrect or outdated.

### User Memory

User memory is a free-form markdown file (~/.dottie/user-memory.md) where the user can write anything they want Dottie to know. Unlike the structured memory key-value store, this is a single document the user controls directly — like a personal README for the agent.

- GET /v1/user-memory — Read the contents of the user memory file. If the file doesn't exist yet, Dottie creates a default one with placeholder sections.
  - Response: { content: string }
- POST /v1/user-memory — Overwrite the user memory file with new content. The entire file is replaced — there is no merge or append behavior.
  - Body: { content: string }

### Events

The events system is Dottie's activity log. Every significant action — a chat message, a tool invocation, a heartbeat — is recorded as an event with a type and associated data. You can query events to build analytics dashboards, understand usage patterns, or debug agent behavior.

- GET /v1/events — Retrieve a list of events, optionally filtered by type and date range. Events are returned in reverse chronological order.
  - type (string, optional): Filter by event type. Common types: "chat", "tool_call", "heartbeat", "error".
  - startDate (string, optional): Only return events after this ISO 8601 date.
  - endDate (string, optional): Only return events before this ISO 8601 date.
  - limit (number, optional): Maximum number of events to return. Defaults to 50.
- GET /v1/events/summary — Get aggregated statistics about events over a time period. Groups and counts events instead of returning individual records.
  - startDate (string, optional): Start of the summary period in ISO 8601 format.
  - endDate (string, optional): End of the summary period in ISO 8601 format.
  - groupBy (string, optional): How to group results. Options: "type", "day", "week", "month". Defaults to "type".
- POST /v1/events — Log a custom event. While Dottie automatically logs its own events, you can use this to record custom application events.
  - Body: { type: string, data: object }

### Preferences

Preferences control how Dottie behaves — the agent's name, personality, whether morning briefs are enabled, and other configurable settings. Stored in ~/.dottie/preferences.json and persist across app restarts.

- GET /v1/preferences — Retrieve all current preferences with their current values.
  - Response: { agentName, agentPersonality, morningBrief, ... }
- PUT /v1/preferences — Update one or more preferences. The request body is merged with existing preferences — fields you include are updated, fields you omit are left unchanged.
  - agentName (string, optional): The display name for the agent. Defaults to "Dottie".
  - agentPersonality (string, optional): A freeform description of how the agent should behave (e.g., "friendly and concise").
  - morningBrief (boolean, optional): Whether the agent should deliver a morning briefing when you first interact each day.

### Sessions

Sessions represent individual conversation threads. Each time a user starts a new conversation, a session is created to group messages together.

- GET /v1/sessions — List all saved sessions. Each session includes an ID, creation timestamp, and a preview of the conversation.
- DELETE /v1/sessions/:id — Permanently delete a session and all its associated messages.

### Tasks

Tasks are scheduled prompts that Dottie executes at specific times. You can create one-off tasks ("remind me to call Mom at 5pm") or recurring tasks ("every morning at 9am, summarize my calendar"). When a task fires, the agent runs the prompt with full tool access.

- GET /v1/tasks — List all scheduled tasks, including name, prompt, schedule, and enabled status.
- POST /v1/tasks — Create a new scheduled task. For recurring tasks, set recurring to true and provide an interval in milliseconds.
  - name (string, required): Human-readable name for the task.
  - prompt (string, required): The message to send to the agent when the task fires. Executed as if the user typed it.
  - runAt (string, required): When to first execute, in ISO 8601 format.
  - recurring (boolean, optional): Whether this task should repeat. Defaults to false.
  - intervalMs (number, optional): Repeat interval in milliseconds. Common values: 86400000 (daily), 604800000 (weekly), 3600000 (hourly).
- PUT /v1/tasks/:id — Update an existing task. Only include the fields you want to change.
- DELETE /v1/tasks/:id — Permanently delete a scheduled task.
- POST /v1/tasks/:id/toggle — Enable or disable a task without deleting it. A disabled task remains in the list but will not execute until re-enabled.
  - Body: { enabled: boolean }

### Heartbeat

The heartbeat system enables Dottie to act proactively — checking in on goals, delivering scheduled updates, and surfacing relevant information without being asked. When a heartbeat fires, the agent evaluates the user's context (upcoming events, active goals, pending reminders) and generates a proactive message if something is worth mentioning.

- GET /v1/heartbeat/stream — Open an SSE stream to receive proactive agent messages in real time. Events: "heartbeat_start", "text_delta", "heartbeat_done". Keep this connection open to receive push-style updates.
- POST /v1/heartbeat/trigger — Manually trigger a heartbeat check-in right now. The agent immediately evaluates context and generates a proactive message if anything is relevant.
- GET /v1/heartbeat/status — Check the current state of the heartbeat system.
  - Response: { enabled, lastRun, nextRun }

### Permissions

The permissions endpoint returns the definitions for every tool permission in the system. Each permission has a name, description, and category. This data powers the Settings UI where users grant or revoke access to specific capabilities.

- GET /v1/permissions — Retrieve the full list of tool permission definitions. Each includes a machine-readable key, human-readable name, description, and category (e.g., "personal-data", "system", "communication").

### Tools

Execute any tool by name — deterministic, no AI, no agent loop. Dottie exposes 134 tools (54 core + 81 macOS system tools) that can be called directly via these endpoints. Tools are filtered by the caller's permission scopes.

- GET /v1/tools — List all tools available to the caller, filtered by active permission scopes. Each tool has a name and description.
  - Response: { tools: [{ name, description }] }
- POST /v1/tools/:name — Execute a tool by name. Runs deterministically with no LLM inference. Returns 403 if the tool requires a permission scope that hasn't been granted.
  - name (string, required, URL param): The tool name (e.g. "weather_get", "get_clipboard", "contacts_list"). Use GET /v1/tools to discover available names.
  - body (object, optional): Tool-specific input parameters as JSON. Varies per tool.
  - Response: { success, data }

## SDK Reference

The Dottie SDK (sdk.js) is a client-side JavaScript library for apps running in the Dottie App Store. Apps run in an iframe and the SDK communicates with the agent service via a postMessage bridge. Include `<script src="/sdk.js"></script>` in your app.

### SDK — AI

- SDK.chat(message, options?) — Send a message to the AI agent and receive a response. Options: { includeMemory: boolean, memoryPattern: string, history: array }.
- SDK.generateImage(prompt) — Generate an image from a text prompt.

### SDK — Tools

- SDK.tool(name, input?) — Execute any tool by name. Deterministic, no LLM. Equivalent to POST /v1/tools/:name.
- SDK.tools() — List all available tools (filtered by app permissions). Equivalent to GET /v1/tools.
- SDK.weather() — Shorthand for SDK.tool('weather_get', {}).
- SDK.notify(message) — Send a system notification. Shorthand for SDK.tool('notify_user', { message }).
- SDK.clipboard.get() — Read clipboard contents.
- SDK.clipboard.set(text) — Write text to clipboard.
- SDK.maps.search(query) — Search for a location.
- SDK.maps.directions(from, to) — Get directions between two locations.
- SDK.goals.list() — List all goals.
- SDK.goals.create(goal) — Create a new goal.
- SDK.webSearch(query, options?) — Search the web. Options: { provider: string }.
- SDK.webFetch(url) — Fetch a URL and return its content.

### SDK — Memory & Storage

- SDK.memoryRead(key) — Read a shared memory entry by key.
- SDK.memoryWrite(key, value) — Write a shared memory entry (cross-app).
- SDK.memoryList() — List all shared memory keys.
- SDK.storageRead(key) — Read a per-app storage entry by key.
- SDK.storageWrite(key, value) — Write a per-app storage entry.
- SDK.storageList() — List all per-app storage keys.

### SDK — Personal Data

Access macOS system data through the SDK.data namespace. Each method maps to a Personal Context Protocol endpoint.

- SDK.data.contacts.list(params?) — List/search contacts.
- SDK.data.contacts.get(name) — Get a specific contact by name.
- SDK.data.calendar.list(params?) — List calendar events.
- SDK.data.calendar.create(body) — Create a calendar event.
- SDK.data.calendar.update(body) — Update a calendar event.
- SDK.data.calendar.remove(body) — Delete a calendar event.
- SDK.data.reminders.list(params?) — List reminders.
- SDK.data.reminders.create(body) — Create a reminder.
- SDK.data.reminders.update(body) — Update a reminder.
- SDK.data.reminders.remove(body) — Delete a reminder.
- SDK.data.mail.list(params?) — List recent emails.
- SDK.data.mail.read(subject) — Read a specific email by subject.
- SDK.data.mail.send(body) — Send an email.
- SDK.data.notes.list(params?) — List notes.
- SDK.data.notes.read(title) — Read a specific note.
- SDK.data.notes.create(body) — Create a note.
- SDK.data.safari.tabs() — Get open Safari tabs.
- SDK.data.files.recent(params?) — Get recently modified files.
- SDK.data.files.search(params?) — Search files via Spotlight.
- SDK.data.files.tags(params?) — List Finder tags.
- SDK.data.photos.list(params?) — Browse photos.
- SDK.data.photos.search(params?) — Search photos by content.
- SDK.data.photos.albums(params?) — List photo albums.
- SDK.data.music.nowPlaying() — Get currently playing track.
- SDK.data.music.search(params?) — Search music library.
- SDK.data.music.play(body) — Play a track.
- SDK.data.music.control(body) — Control playback (pause, play, next, previous).
- SDK.data.screenshot(params?) — Capture a screenshot.

### SDK — Events & Permissions

- SDK.logEvent(eventType, data, context?) — Log a custom event.
- SDK.getEvents(options?) — Query events with filters.
- SDK.getEventStats(groupBy?) — Get aggregated event statistics.
- SDK.getPermissions() — Get the app's current permission scopes.
- SDK.hasPermission(scope) — Check if a specific permission scope is granted.
- SDK.getUser() — Get the current user context.

### Permission Scopes

All permission scopes default to off. Apps must request specific scopes.

| Scope | Tools | Description |
|---|---|---|
| calendar.read | calendar_list, calendar_create | Read calendar events |
| calendar.destructive | calendar_update, calendar_delete | Modify/delete calendar events |
| reminders.read | reminder_list, reminder_create | Read reminders |
| reminders.destructive | reminder_update, reminder_delete | Modify/delete reminders |
| contacts.read | contacts_list, contacts_get | Read contacts |
| mail.read | mail_list, mail_read | Read emails |
| mail.send | mail_send | Send emails |
| notes.read | notes_list, notes_read | Read notes |
| notes.write | notes_create | Create notes |
| safari.read | safari_tabs | See open Safari tabs |
| files.read | files_recent, files_search, files_tags | Search/access files |
| photos.read | photos_list, photos_search, photos_albums | Browse photo library |
| music.read | music_now_playing, music_search | See music library |
| music.control | music_play, music_control | Control music playback |
| screenshot | screenshot | Take screenshots |

## Personal Context Protocol

Personal Context Protocol endpoints access macOS system data. Each category requires specific permission scopes. These endpoints let you build features that understand the user's personal context — their contacts, schedule, emails, files, photos, and more.

### Contacts (requires contacts.read)

Access the user's macOS Contacts database. Search across all contact fields or retrieve a specific contact by name. Useful for looking up phone numbers, pre-filling email recipients, or providing the agent with context about who someone is.

- GET /v1/contacts — Search across all contacts. The search query matches against names, emails, phone numbers, and other fields. Case-insensitive, supports partial matching.
  - search (string, optional): Search term. Omit to return all contacts.
  - limit (number, optional): Maximum number of contacts to return.
- GET /v1/contacts/:name — Retrieve a specific contact by full or partial name. Returns the complete contact record including phone numbers, email addresses, physical addresses, birthday, and notes.

### Calendar (read: calendar.read, mutate: calendar.destructive)

Read, create, update, and delete events in macOS Calendar. Integrates with all calendar sources (iCloud, Google, Exchange, local). Use this to help users manage their schedule, check availability, or create meetings.

- GET /v1/calendar — Retrieve upcoming calendar events. Each event includes title, start/end times, location, notes, and calendar source.
  - days (number, optional): How many days ahead to look. Defaults to 7. Set to 1 for today's events, 30 for a monthly view.
  - calendar (string, optional): Filter to a specific calendar by name (e.g., "Work", "Personal").
- POST /v1/calendar — Create a new calendar event.
  - title (string, required): The name of the event.
  - startDate (string, required): When the event starts, in ISO 8601 format.
  - endDate (string, required): When the event ends, in ISO 8601 format.
  - calendar (string, optional): Which calendar to add the event to. Defaults to the user's default calendar.
- PUT /v1/calendar — Update an existing calendar event by title.
  - Body: { title: string, updates: { notes, startDate, endDate, calendar } }
- DELETE /v1/calendar — Delete a calendar event by title.
  - Body: { title: string }

### Reminders (read: reminders.read, mutate: reminders.destructive)

Read, create, update, and delete items in macOS Reminders. Reminders can have due dates, notes, and belong to different lists. Perfect for task management features.

- GET /v1/reminders — List all reminders, optionally filtered to a specific list.
  - list (string, optional): Filter to a specific list (e.g., "Groceries", "Work").
- POST /v1/reminders — Create a new reminder.
  - title (string, required): The reminder text.
  - notes (string, optional): Additional details or context.
  - dueDate (string, optional): When the reminder is due, in ISO 8601 format.
  - list (string, optional): Which reminders list to add it to. Defaults to the user's default list.
- PUT /v1/reminders — Update an existing reminder by title.
  - Body: { title: string, updates: { notes, dueDate, list } }
- DELETE /v1/reminders — Delete a reminder by title.
  - Body: { title: string }

### Mail (read: mail.read, send: mail.send)

Access macOS Mail to read emails and send new messages. Enables email-aware features like summarizing unread mail, drafting replies, or triaging the inbox.

- GET /v1/mail — List recent emails from a mailbox. Each email includes sender, subject, date, and a preview of the body.
  - mailbox (string, optional): Which mailbox to read from (e.g., "INBOX", "Sent", "Drafts"). Defaults to inbox.
  - limit (number, optional): Maximum number of emails to return.
- GET /v1/mail/:subject — Retrieve a specific email by subject line. Returns the full email including sender, recipients, date, subject, and complete body text. Case-insensitive matching.
- POST /v1/mail — Compose and send a new email immediately through the user's default mail account.
  - to (string, required): Recipient email address. Separate multiple addresses with commas.
  - subject (string, required): Email subject line.
  - body (string, required): Email body text. Plain text only.

### Notes (read: notes.read, write: notes.write)

Access macOS Notes to read existing notes and create new ones. Notes can be organized into folders. Useful for capturing ideas, saving conversation info, or referencing existing notes during chat.

- GET /v1/notes — List all notes, optionally filtered to a specific folder.
  - folder (string, optional): Filter to a specific folder (e.g., "Work", "Personal").
- GET /v1/notes/:title — Retrieve a specific note by title. Returns full content including title, body, folder, and modification date. Case-insensitive matching.
- POST /v1/notes — Create a new note.
  - title (string, required): The title of the new note.
  - body (string, required): The content of the note. Plain text.
  - folder (string, optional): Which Notes folder to save in. May be created automatically if it doesn't exist.

### Safari (requires safari.read)

Access currently open Safari tabs. Gives the agent awareness of what the user is browsing — enabling features like "summarize this page" or using browsing context for more relevant responses.

- GET /v1/safari/tabs — Get all currently open Safari tabs across all windows. Each tab includes the page URL and title. Use this to understand what the user is looking at or to let them reference a tab in conversation.

### Files (requires files.read)

Search and browse the user's file system. Find recently modified files, search by name or content, and list Finder tags. Enables file-aware features like helping users find documents or understanding their workspace.

- GET /v1/files/recent — Get recently modified files, sorted by modification time (most recent first).
  - limit (number, optional): Maximum number of files to return.
- GET /v1/files/search — Search for files by name or content using macOS Spotlight. Fast and searches across all indexed locations.
  - query (string, required): Search term matched against file names and content. Supports natural language queries.
  - folder (string, optional): Restrict search to a specific folder path (e.g., "~/Documents").
- GET /v1/files/tags — List all Finder tags currently in use. Finder tags are color-coded labels for file organization (e.g., "Important", "Work", "To Review").

### Photos (requires photos.read)

Access the user's Photos library to browse, search, and list albums. Integrates with macOS Photos including iCloud Photos if enabled.

- GET /v1/photos — List photos, optionally filtered to a specific album.
  - limit (number, optional): Maximum number of photos to return.
  - album (string, optional): Filter to a specific album (e.g., "Favorites", "Vacation 2025").
- GET /v1/photos/search — Search for photos using natural language. Leverages macOS on-device image analysis to find images by visual content (e.g., "beach", "dog", "birthday party").
  - query (string, required): Natural language search query describing what you're looking for.
- GET /v1/photos/albums — List all photo albums including smart albums and user-created albums, with photo counts.

### Music (read: music.read, playback: music.control)

Control Apple Music and browse the music library. See what's playing, search for songs, start playback, and control the player. Enables features like "what song is this?" or "play something relaxing."

- GET /v1/music/now-playing — Get the currently playing track including song title, artist, album, duration, and playback position.
- GET /v1/music/search — Search the user's Apple Music library by song title, artist, or album name.
  - query (string, required): Search term. Case-insensitive.
- POST /v1/music/play — Start playing a track from the user's library.
  - query (string, required): The song, artist, or album to play.
  - shuffle (boolean, optional): Set to true to shuffle the playback queue. Defaults to false.
- POST /v1/music/control — Control playback: pause, resume, skip, or go back.
  - action (string, required): One of "pause", "play", "next", or "previous".

### Screenshot (requires screenshot permission)

Capture screenshots of the user's screen. Enables visual awareness — the agent can see what's on screen for visual troubleshooting or content capture.

- POST /v1/screenshot — Take a screenshot and save it to a file. The captured image can be analyzed by the agent to understand visual context.
  - type (string, required): The type of screenshot. Currently supports "screen" for full-screen capture.
  - filename (string, required): The filename to save the screenshot as (e.g., "capture.png").

## Tools Reference

Dottie exposes 134 tools total (54 core + 81 macOS system, with 1 override). The custom `notify_user` overrides the core version, so 125 unique tools are available. Tools are callable via the agent chat loop or deterministically via `POST /v1/tools/:name`.

### Core Tools (54)

| Tool | Description |
|------|-------------|
| app_generate | Generate a React app component from a natural language description. Returns executable JavaScript code that uses React.createElement() (no JSX). |
| app_validate | Validate that generated React component code is syntactically correct and follows the expected structure. |
| browser_click | Click an element on the current page by CSS selector or visible text. |
| browser_close | Close the current browser session. |
| browser_extract | Extract structured data from the current page using CSS selectors. Returns an array of objects with the requested fields. |
| browser_navigate | Navigate a headless browser to a URL and return the page title and text content. Preferred tool for reading web pages -- renders JavaScript so it works on dynamic sites. |
| browser_read_page | Read the current page content or a specific section. |
| browser_screenshot | Take a screenshot of the current page and save it as a PNG. Returns an accessibility summary and the screenshot URL. |
| browser_type | Type text into an input field on the current page. Finds the field by CSS selector, label, or placeholder text. |
| cancel_job | Cancel/delete a scheduled job by its ID. |
| event_query | Query user activity events with filters. Returns recent events matching the criteria. |
| events_summary | Get aggregated usage statistics and analytics. Shows counts by event type. |
| file_delete | Delete a file or folder from the user's virtual filesystem. |
| file_list | List files and folders in a directory of the user's virtual filesystem. |
| file_move | Move or rename a file in the user's virtual filesystem. |
| file_read | Read the contents of a file from the user's virtual filesystem. |
| file_write | Write content to a file in the user's virtual filesystem. |
| folder_create | Create a new folder in the user's virtual filesystem. |
| goal_complete | Mark a goal as completed. |
| goal_create | Create a new goal with optional steps, priority, deadline, and category. |
| goal_delete | Delete a goal permanently. |
| goal_list | List all goals for the user, optionally filtered by status or category. |
| goal_plan | Break down a goal into detailed steps with action prompts. Use this to add or replace steps on an existing goal. |
| goal_search | Search goals by text in description or steps. |
| goal_stats | Get goal statistics (total, completed, in progress, by category, etc.). |
| goal_step | Execute the next pending step on a goal automatically via scheduled task. |
| goal_step_done | Mark the current in-progress step as completed and record its result. |
| goal_work | Start executing the next pending step on a goal. Returns the step's action prompt. |
| grokipedia_search | Look up a topic on Grokipedia, a Wikipedia-like encyclopedia. |
| image_generate | Generate an AI image from a text prompt. |
| image_list | List the user's photos and generated images. Returns the most recent images with their prompts and dates. |
| image_search | Search the user's photos and generated images by prompt text. |
| list_jobs | List all scheduled jobs (active and completed). |
| memory_delete | Delete a specific memory by its key. Use when the user asks to forget something or remove outdated information. |
| memory_list | List all memories saved in the knowledge graph. Returns all memory keys and their content. |
| memory_read | Read a specific memory by its exact key. |
| memory_save | Save an important fact, preference, or piece of information to long-term memory. |
| memory_search | Search long-term memory for previously saved information. |
| memory_update | Update an existing memory or create a new one with a specific key. |
| message_delete | Delete an entire conversation with a specific person. |
| message_list | List the user's message conversations. |
| message_read | Read messages in a conversation with a specific person. |
| message_send | Send a message in a conversation. Creates a new conversation if one doesn't exist with the recipient. |
| notify_user | Send a notification to the user. Use during heartbeat or scheduled tasks to proactively inform the user. (Overridden by macOS custom version.) |
| run_code | Execute JavaScript code and return the output. The code runs in a Node.js subprocess. |
| schedule_job | Schedule a job to run later or on a recurring basis. The job sends a message to the agent at the scheduled time. |
| toggle_job | Enable or disable a scheduled job without deleting it. |
| trigger_create | Create an event-driven trigger that fires when a specific event occurs. |
| trigger_delete | Delete a trigger permanently. |
| trigger_list | List all triggers, optionally filtered by enabled status or event type. |
| trigger_toggle | Enable or disable a trigger without deleting it. |
| weather_get | Get the current weather for a location. |
| web_fetch | Make an HTTP request and return the response. Supports GET, POST, PUT, PATCH, and DELETE. |
| web_search | Search the web for current information. Use once per question to find the right URL, then use browser_navigate to read the page. |

### macOS System Tools (81)

| Tool | Description |
|------|-------------|
| app_list_open | List all currently running applications. |
| app_search | Search for installed applications using Spotlight. |
| alarm_cancel | Cancel an alarm by label or cancel all alarms. |
| alarm_set | Set an alarm for a specific time (e.g., "7am", "3:30pm", "15:00"). |
| avatar_get | Get your current visual avatar React component code. |
| avatar_update | Create or update your visual avatar displayed in the Avatar app window. Provide a React component as a JavaScript code string. |
| brightness_down | Decrease screen brightness. Each step is approximately 6% (16 steps total). |
| brightness_up | Increase screen brightness. Each step is approximately 6% (16 steps total). |
| calendar_create | Create a calendar event. |
| calendar_delete | Delete a calendar event. |
| calendar_list | List upcoming calendar events from macOS Calendar.app. |
| calendar_update | Update an existing calendar event (change title, time, or date). |
| close_app | Quit/close a running macOS application. |
| code_open | Open a code snippet in Visual Studio Code for editing or review. |
| code_read_active | Read the content of the currently active file in VS Code. |
| code_write | Write or update a code file. Can write to the active VS Code file or a specified path. |
| contacts_get | Get full details for a contact (phone, email, address). |
| contacts_list | List contacts from the address book. Can search by name. |
| dark_mode_toggle | Toggle between dark and light mode appearance. |
| do_not_disturb | Toggle Focus/Do Not Disturb mode. |
| files_recent | List recently opened files from Finder. |
| files_search | Search for files using Spotlight (filename or content). |
| files_tags | Get or set Finder tags on a file. |
| get_clipboard | Read the current clipboard contents (text only). |
| get_frontmost_app | Get the name of the currently active (frontmost) macOS application. |
| get_frontmost_url | Get the URL from the frontmost browser tab. Supports Safari, Chrome, Arc, Brave, Edge, Firefox. |
| get_selected_text | Get the currently selected text from the frontmost application (requires accessibility permission). |
| hide_all_apps | Hide all applications except Finder, clearing the screen. |
| mail_list | List recent emails from Mail.app. |
| mail_read | Read the content of a specific email by subject. |
| mail_send | Compose and send an email via Mail.app. |
| maps_directions | Get directions between two locations in Apple Maps. |
| maps_pin | Drop a pin at specific coordinates in Apple Maps. |
| maps_search | Search for a location or place and open it in Apple Maps. |
| media_next | Skip to the next track for system-wide media playback. Works with any app. |
| media_play_pause | Toggle play/pause for system-wide media. Works with any app (browsers, Spotify, Music.app, etc). |
| media_previous | Go to the previous track for system-wide media playback. Works with any app. |
| music_play | Play a specific song, artist, or album by opening Spotify search. |
| notes_create | Create a new note in Notes.app. |
| notes_list | List notes from Notes.app. |
| notes_read | Read the content of a specific note by title. |
| notify_user | Send a native macOS notification to the user. Appears in Notification Center. Overrides the core notify_user tool. |
| open_app | Open a macOS application by name. |
| open_url | Open a URL in the default web browser. |
| photos_albums | List all photo albums. |
| photos_list | List recent photos from Photos.app. |
| photos_search | Search photos by keyword, date, or location. |
| reminder_create | Create a reminder in the Reminders app. |
| reminder_delete | Delete a reminder from the Reminders app. |
| reminder_list | List reminders from the Reminders app. |
| reminder_update | Update an existing reminder (mark complete, change title, or reschedule). |
| safari_tabs | List currently open Safari browser tabs with their URLs and titles. |
| screenshot | Take a screenshot of the Mac desktop, a window, or a user selection. |
| screenshot_and_analyze | Take a screenshot and analyze the visual content with AI vision. |
| set_clipboard | Set the clipboard to specified text. |
| shopping_list_add | Add an item to the shopping list. |
| shopping_list_clear | Clear all items from the shopping list. |
| shopping_list_remove | Remove an item from the shopping list. |
| shopping_list_view | View all items on the shopping list. |
| show_desktop | Show desktop by minimizing all windows (like hot corner or F11). |
| store_app_open | Open a Dottie App Store app in the browser via the local app host. |
| store_install | Install an app from the Dottie App Store. |
| store_open | Open the Dottie App Store in the browser to browse and install apps. |
| store_search | Search the Dottie App Store for apps by name, description, or category. |
| store_uninstall | Uninstall an app from dottie-desktop. |
| timer_cancel | Cancel a timer by label or cancel all timers. |
| timer_list | List all active timers. |
| timer_set | Set a countdown timer (e.g., "5 minutes", "30 seconds", "1h 30m"). |
| type_text | Type text at the current cursor position using Dottie deep link. |
| type_text_at_cursor | Type text at the current cursor position (requires accessibility permission). |
| user_memory_append | Append a note to the user's personal memory file. |
| user_memory_get | Read the user's personal memory file. |
| user_memory_update | Update the user's personal memory file. |
| volume_down | Decrease system volume by 10% (one Alexa-style step). |
| volume_get | Get current system volume level. |
| volume_mute | Mute or unmute system audio. |
| volume_set | Set system volume using Alexa-style 0-10 scale. |
| volume_up | Increase system volume by 10% (one Alexa-style step). |
| window_close | Close a specific macOS window by app name and optional window title. |
| window_focus | Bring a specific macOS window to the front by app name and optional window title. |
| window_list | List all visible windows with their app name, window title, and position. |