@vox-ai-app/integrations

@vox-ai-app/integrations

macOS system integrations for Vox: Apple Mail, Screen control, iMessage, Contacts, Shortcuts, Music, Calendar, and Reminders. Each integration ships with tool implementations and LLM tool definitions.

Requires macOS. Each integration needs specific system permissions granted by the user.

Install

npm install @vox-ai-app/integrations

Peer dependency: electron >= 28

Exports

Export	Contents
@vox-ai-app/integrations	All exports
@vox-ai-app/integrations/defs/mail	Mail tool definitions
@vox-ai-app/integrations/defs/screen	Screen tool definitions
@vox-ai-app/integrations/defs/imessage	iMessage tool definitions
@vox-ai-app/integrations/defs/contacts	Contacts tool definitions
@vox-ai-app/integrations/defs/shortcuts	Shortcuts tool definitions
@vox-ai-app/integrations/defs/music	Music tool definitions
@vox-ai-app/integrations/defs/calendar	Calendar tool definitions
@vox-ai-app/integrations/defs/reminders	Reminders tool definitions
@vox-ai-app/integrations/mail	Mail functions
@vox-ai-app/integrations/screen	Screen capture + control
@vox-ai-app/integrations/screen/capture	Capture only
@vox-ai-app/integrations/screen/control	Control only
@vox-ai-app/integrations/screen/queue	Session acquire/release
@vox-ai-app/integrations/imessage	iMessage data, reply, service
@vox-ai-app/integrations/contacts	Contacts search
@vox-ai-app/integrations/shortcuts	List and run Shortcuts
@vox-ai-app/integrations/music	Apple Music control
@vox-ai-app/integrations/calendar	Calendar events CRUD
@vox-ai-app/integrations/reminders	Reminders management

Mail

Requires Automation permission for Mail (System Settings → Privacy & Security → Automation).

import { sendEmail, readEmails, searchContacts, replyToEmail } from '@vox-ai-app/integrations/mail'

const emails = await readEmails({ account: 'Work', folder: 'INBOX', limit: 20 })
await sendEmail({ to: '[e-mail]', subject: 'Hi', body: 'Hello.' })
await replyToEmail({ messageId: '...', body: 'Thanks!' })

Tool definitions:

import { MAIL_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/mail'

Screen

Requires Accessibility permission (System Settings → Privacy & Security → Accessibility).

import {
  captureFullScreen,
  clickAt,
  typeText,
  getUiElements
} from '@vox-ai-app/integrations/screen'
import { acquireScreen, releaseScreen } from '@vox-ai-app/integrations/screen/queue'

const session = await acquireScreen()
try {
  const img = await captureFullScreen()
  await clickAt({ x: 100, y: 200 })
  await typeText({ text: 'Hello' })
} finally {
  await releaseScreen(session)
}

Tool definitions:

import { SCREEN_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/screen'

iMessage

Requires Full Disk Access (System Settings → Privacy & Security → Full Disk Access).

Tool use (read conversations, send messages)

import { listConversations, listContacts, sendReply } from '@vox-ai-app/integrations/imessage'

const conversations = listConversations()
const contacts = listContacts()
await sendReply('[phone]', 'Hello from Vox!')

Gateway service (AI replies to incoming iMessages)

import { createIMessageService } from '@vox-ai-app/integrations/imessage'

const svc = createIMessageService({
  logger,
  onTranscript: (text, handle) => {
    /* emit to UI */
  },
  onOpenSettings: () => shell.openExternal('x-apple.systempreferences:...'),
  onMessage: async (text, handle) => {
    // call your AI here, return the reply string
    return await askAI(text)
  }
})

svc.start('my-passphrase')
// user sends "my-passphrase\nWhat's the weather?" → AI replies back

onMessage must return a Promise<string | null>. Returning null skips the reply.

Tool definitions:

import { IMESSAGE_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/imessage'

Contacts

Requires Contacts permission (System Settings → Privacy & Security → Contacts).

import { searchContacts } from '@vox-ai-app/integrations/contacts'

const result = await searchContacts({ query: 'John', limit: 25, offset: 0 })
// { count, total, limit, offset, has_more, items: [{ name, emails, phones, org, title, addresses, notes }] }

Tool definitions:

import { CONTACTS_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/contacts'

Shortcuts

import { listShortcuts, runShortcut } from '@vox-ai-app/integrations/shortcuts'

const result = await listShortcuts({ limit: 100, offset: 0 })
// { count, total, limit, offset, has_more, items: ['Shortcut Name', ...] }

const output = await runShortcut({ name: 'My Shortcut', input: 'hello' })

Tool definitions:

import { SHORTCUTS_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/shortcuts'

Music

Requires Media & Apple Music permission (System Settings → Privacy & Security → Media & Apple Music).

import {
  getNowPlaying,
  playMusic,
  pauseMusic,
  nextTrack,
  previousTrack,
  setVolume
} from '@vox-ai-app/integrations/music'

const track = await getNowPlaying()
await playMusic({ query: 'Bohemian Rhapsody' })
await pauseMusic()
await nextTrack()
await previousTrack()
await setVolume({ level: 50 })

Tool definitions:

import { MUSIC_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/music'

Calendar

Requires Calendars permission (System Settings → Privacy & Security → Calendars).

import { listEvents, createEvent, updateEvent, deleteEvent } from '@vox-ai-app/integrations/calendar'

const result = await listEvents({ from: '2026-04-01', to: '2026-04-30', limit: 25, offset: 0 })
// { count, total, limit, offset, has_more, items: [{ title, start, end, location, notes, calendar }] }

await createEvent({ title: 'Meeting', start: '2026-04-15T10:00', end: '2026-04-15T11:00' })
await updateEvent({ title: 'Meeting', newTitle: 'Updated Meeting' })
await deleteEvent({ title: 'Meeting', date: '2026-04-15' })

Tool definitions:

import { CALENDAR_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/calendar'

Reminders

Requires Reminders permission (System Settings → Privacy & Security → Reminders).

import { listReminders, createReminder, completeReminder } from '@vox-ai-app/integrations/reminders'

const result = await listReminders({ list: 'Work', limit: 25, offset: 0 })
// { count, total, limit, offset, has_more, items: [{ name, list, dueDate, completed, notes }] }

await createReminder({ name: 'Buy groceries', list: 'Personal', dueDate: '2026-04-15' })
await completeReminder({ name: 'Buy groceries', list: 'Personal' })

Tool definitions:

import { REMINDERS_TOOL_DEFINITIONS } from '@vox-ai-app/integrations/defs/reminders'

License

MIT