@vox-ai-app/integrations

@vox-ai-app/vox-integrations

macOS system integrations for Vox: Apple Mail, Screen control, and iMessage. 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/vox-integrations

Peer dependency: electron >= 28

Exports

Export	Contents
@vox-ai-app/vox-integrations	All exports
@vox-ai-app/vox-integrations/defs	All tool definitions
@vox-ai-app/vox-integrations/mail	Mail functions
@vox-ai-app/vox-integrations/screen	Screen capture + control
@vox-ai-app/vox-integrations/screen/capture	Capture only
@vox-ai-app/vox-integrations/screen/control	Control only
@vox-ai-app/vox-integrations/screen/queue	Session acquire/release
@vox-ai-app/vox-integrations/imessage	iMessage data, reply, service

Mail

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

import {
  sendEmail,
  readEmails,
  searchContacts,
  replyToEmail
} from '@vox-ai-app/vox-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/vox-integrations/defs'

Screen

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

import {
  captureFullScreen,
  clickAt,
  typeText,
  getUiElements
} from '@vox-ai-app/vox-integrations/screen'
import { acquireScreen, releaseScreen } from '@vox-ai-app/vox-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/vox-integrations/defs'

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/vox-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/vox-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/vox-integrations/defs'

License

MIT