- A custom toolkit wraps local iMessage (send, contacts, history, memory) as Composio tools.
- In-process execution runs each tool right on your Mac through
session.execute, with no remote API. - One session puts those local tools on the same surface as the 1000+ app catalog.
- The eve provider turns
session.tools()into eve-native tools, soeve devcan call them. - Triggers let an outside event wake the agent and reach your phone, with in-chat auth through
COMPOSIO_MANAGE_CONNECTIONSfor any app you haven’t connected.
Setup
You need a Composio API key and macOS (the iMessage tools drive Messages.app, Contacts.app, and the localchat.db).
1
Install
Install
2
Configure
Configure
.env.local
3
Grant macOS permissions
Grant macOS permissions (prompted on first use): Automation for Messages, Contacts access, and Full Disk Access to read
chat.db.The custom toolkit
A custom toolkit is a named group of custom tools. Each tool declares an input schema and anexecute that runs locally. Here is SEND, which shells out to AppleScript to drive Messages.app:
imessage/send-message.ts — complete file
The execute runs locally on your Mac, driving Messages.app through osascript.
imessage/send-message.ts
FIND_CONTACT (fuzzy contact lookup over Contacts.app), READ_MESSAGES (recent messages from chat.db), and RECALL/REMEMBER (per-contact memory), each built the same way:
imessage/index.ts
@composio/core, so it drops into any Composio agent. Custom tools execute in-process through session.execute, which is why they aren’t on the MCP URL yet.
Wire it up
Set the eve provider on the client and register the toolkit on the session.composio.ts grows in three steps, one Composio concept each:
Create the client with the eve provider
The provider is what makessession.tools() return eve-native tools instead of raw Composio tools. Its approval policy pauses every iMessage send before the local AppleScript runs.
composio.ts — step 1: Client with the eve provider
The eve provider makes session.tools() return eve-native tools, so eve can call them directly.
composio.ts
Scope a session to the user
sessions.create gives this user their own toolset, already wired to the full Composio catalog.
composio.ts — step 2: A session for the user
sessions.create scopes the toolset to one user. It already exposes the whole Composio catalog.
composio.ts
Register the local toolkit
Pass the custom toolkit throughexperimental.customToolkits, and the local iMessage tools join the catalog on the same session.
composio.ts — step 3: Register the local toolkit
Pass the custom toolkit so the local iMessage tools join the catalog on the same session.
composio.ts
defineComposioTools(session) returns the resolver that exposes session.tools(). One line:
agent/tools/composio.ts
agent/agent.ts
eve dev and talk to it. The agent can text a contact, read a thread, and act across every connected app, with auth handled in chat through COMPOSIO_MANAGE_CONNECTIONS.
Extend it: triggers
The agent can text, so anything that can wake the agent can reach your phone. Composio triggers turn an external event into an agent run: subscribe to an app event, point Composio’s webhook at your app, and act on each event with the same iMessage tools. For example, surface a Linear assignment and ask the user whether to inspect it. The first turn contains no issue title or body, so third-party text does not cross into the agent prompt before the user opts in:agent/channels/triggers.ts
composio client from composio.ts:
agent/setup-triggers.ts
npx tsx agent/setup-triggers.ts, and the webhook handler above takes over from there.
Swap the trigger and the prompt to create another reflex. Keep the first turn content-free, then fetch third-party content only after the user asks to continue.
More reflexes
The prompt is where each reflex earns its keep, but the webhook should not turn untrusted content into instructions. Here is the same two-step gate for Gmail:agent/channels/triggers.ts
- Stand-up nudge. A calendar event ten minutes out texts you the agenda and the meeting link, pulled straight from the invite.
- Review request. A new GitHub review request texts you the PR title and a one-line read of the diff, so you can reply “approve” from your phone.
- Money in. A successful Stripe payment texts you the amount and the customer, no dashboard required.
- Cover for me. A Slack mention while you’re away texts a teammate and asks them to take a look.
Browse the project
The key files, in one place. The custom toolkit and the session wiring carry the integration, the eve provider is imported from@composio/experimental/eve, and the rest is local macOS glue.
The iMessage implementation is maintained in platform-imessage.
Run it
The browser above is an implementation slice, not a standalone fixture: it omits the project’s package manifest and supportinghandles, chat-db, and memory modules. The complete runnable project will be published in the Composio examples repo. Until then, use the provider walkthrough on this page in an existing eve app and treat the iMessage source as a reference for the local toolkit. The first send or contact lookup prompts for macOS permission, and the first time the agent needs an app you haven’t connected, it returns an auth link in chat through COMPOSIO_MANAGE_CONNECTIONS.