Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 268 lines 11.5 KB
Raw
1 ---
2 title: iMessage local toolkit with eve
3 description: Walk through an agent that texts on your behalf from your own Mac. A Composio local toolkit wraps iMessage in-process, and the eve provider puts it on the same session as the whole Composio catalog.
4 keywords:
5 [local toolkit, imessage, local tools, custom toolkit, eve, provider, session, custom tools, macOS, applescript]
6 full: true
7 gallery:
8 categories: [General agents, Background agents]
9 logos: [gmail, linear, github]
10 featured: true
11 order: 3
12 ---
13
14 {/* code-example: single-language-page reason="iMessage agent is a TypeScript-only eve example project" */}
15
16 Most Composio toolkits call a remote API. Some capabilities only exist on one machine, and iMessage is the classic case: there's no iMessage cloud API, so the agent has to run on your Mac and drive Messages.app directly.
17
18 This example builds exactly that: a terminal agent that **texts on your behalf from your own Mac** and reaches the rest of your apps (Gmail, Calendar, GitHub, Slack) through the Composio catalog in the same breath.
19
20 ```
21 you › read my last email and text Shams a summary
22 you › text mom i'm running 10 min late
23 you › what did Lena and I last text about?
24 ```
25
26 The pattern is the takeaway, not iMessage specifically. It comes together from a handful of Composio pieces:
27
28 1. **A local toolkit** wraps local iMessage (send, contacts, history, memory) as Composio tools.
29 2. **In-process execution** runs each tool right on your Mac through `session.execute`, with no remote API.
30 3. **One session** puts those local tools on the same surface as the %TOOLKIT_COUNT% toolkit catalog.
31 4. **The eve provider** turns `session.tools()` into [eve](https://github.com/vercel/eve)-native tools, so `eve dev` can call them.
32 5. **Triggers** let an outside event wake the agent and reach your phone, with in-chat auth through `COMPOSIO_MANAGE_CONNECTIONS` for any app you haven't connected.
33
34 <ImessageFlow />
35
36 Below you build the integration core: the local toolkit first, then the wiring that puts it on a session, then triggers, then a browse of the relevant source. You bring a Composio API key and a Mac. Composio brings the catalog.
37
38 ## Setup
39
40 You need a [Composio API key](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=examples-imessage-agent) and macOS (the iMessage tools drive Messages.app, Contacts.app, and the local `chat.db`).
41
42 <Steps>
43 <Step>
44 **Install**
45
46 ```bash
47 npm install @composio/core @composio/experimental eve
48 ```
49
50 </Step>
51 <Step>
52 **Configure**
53
54 ```txt title=".env.local"
55 COMPOSIO_API_KEY=xxxxxxxxx
56 ```
57
58 </Step>
59 <Step>
60 **Grant macOS permissions** (prompted on first use): Automation for Messages, Contacts access, and Full Disk Access to read `chat.db`.
61 </Step>
62 </Steps>
63
64 ## The local toolkit
65
66 A local toolkit is a named group of local tools. Each tool declares an input schema and an `execute` that runs locally. Here is `SEND`, which shells out to AppleScript to drive Messages.app:
67
68 <FileBuildup name="send" />
69
70 Group your tools into a toolkit. The full project also ships `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:
71
72 ```ts title="imessage/index.ts"
73 // @noErrors
74 import { experimental_createToolkit } from '@composio/core';
75 import { sendMessage } from './send-message';
76 import { findContact } from './find-contact';
77 import { readMessages } from './read-messages';
78 import { recallContact, rememberContact } from './memory-tools';
79
80 export function createImessageToolkit() {
81 return experimental_createToolkit('IMESSAGE', {
82 name: 'iMessage',
83 description:
84 "Send and read iMessages, look up contacts, and remember people, locally on the user's Mac.",
85 tools: [sendMessage, findContact, readMessages, recallContact, rememberContact],
86 });
87 }
88 ```
89
90 The toolkit depends only on `@composio/core`, so it drops into any Composio agent. Local tools execute in-process through `session.execute`, which is why they aren't on the MCP URL yet.
91
92 ## Wire it up
93
94 Set the [eve provider](/docs/providers/eve) on the client and register the toolkit on the session. `composio.ts` grows in three steps, one Composio concept each:
95
96 ### Create the client with the eve provider
97
98 The provider is what makes `session.tools()` return eve-native tools instead of raw Composio tools. Its approval policy pauses every iMessage send before the local AppleScript runs.
99
100 <FileBuildup name="wiring" step={1} />
101
102 ### Scope a session to the user
103
104 `sessions.create` gives this user their own toolset, already wired to the full Composio catalog.
105
106 <FileBuildup name="wiring" step={2} />
107
108 ### Register the local toolkit
109
110 Pass the local toolkit through `experimental.localToolkits`, and the local iMessage tools join the catalog on the same session.
111
112 <FileBuildup name="wiring" step={3} />
113
114 Now hand that session to eve. eve discovers tools from files, so `defineComposioTools(session)` returns the resolver that exposes `session.tools()`. One line:
115
116 ```ts title="agent/tools/composio.ts"
117 // @noErrors
118 import { defineComposioTools } from '@composio/experimental/eve';
119 import { session } from '../../composio';
120
121 export default defineComposioTools(session);
122 ```
123
124 ```ts title="agent/agent.ts"
125 // @noErrors
126 import { defineAgent } from 'eve';
127
128 export default defineAgent({
129 model: 'google/gemini-2.5-flash',
130 });
131 ```
132
133 That's the whole integration. Run `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`.
134
135 ## Extend it: triggers
136
137 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.
138
139 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:
140
141 ```ts title="agent/channels/triggers.ts"
142 // @noErrors
143 import { defineChannel, POST } from 'eve/channels';
144 import { composio } from '../../composio';
145
146 export default defineChannel({
147 routes: [
148 POST('/webhook', async (req, { send }) => {
149 const { payload: event } = await composio.triggers.parse(req, {
150 verifySecret: process.env.COMPOSIO_WEBHOOK_SECRET,
151 });
152 if (event.userId !== 'user_123' || event.triggerSlug !== 'LINEAR_ISSUE_ASSIGNED') {
153 return new Response(null, { status: 202 });
154 }
155 await send(
156 `A verified Linear assignment event arrived. Ask whether I want to inspect it. ` +
157 `Do not call tools in this turn. Event reference: ${event.uuid}.`,
158 {
159 auth: {
160 authenticator: 'composio-webhook',
161 principalType: 'service',
162 principalId: event.userId,
163 attributes: { triggerSlug: event.triggerSlug },
164 },
165 continuationToken: event.uuid,
166 }
167 );
168 return new Response(null, { status: 202 });
169 }),
170 ],
171 });
172 ```
173
174 Point Composio at your webhook and create the trigger, once each. Reuse the same `composio` client from `composio.ts`:
175
176 ```ts title="agent/setup-triggers.ts"
177 // @noErrors
178 import { composio } from '../composio';
179
180 // Register the webhook URL once per project; store the returned
181 // secret as COMPOSIO_WEBHOOK_SECRET.
182 const subscription = await composio.triggers.setWebhookSubscription({
183 webhookUrl: `${process.env.APP_URL}/webhook`,
184 });
185
186 // Use the exact slug from the Composio triggers catalog.
187 const trigger = await composio.triggers.create('user_123', 'LINEAR_ISSUE_ASSIGNED');
188 console.log(`Trigger created: ${trigger.triggerId}`);
189 ```
190
191 Run it once with `npx tsx agent/setup-triggers.ts`, and the webhook handler above takes over from there.
192
193 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.
194
195 ## More reflexes
196
197 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:
198
199 ```ts title="agent/channels/triggers.ts"
200 // @noErrors
201 import { defineChannel, POST } from 'eve/channels';
202 import { composio } from '../../composio';
203
204 export default defineChannel({
205 routes: [
206 POST('/webhook', async (req, { send }) => {
207 const { payload: event } = await composio.triggers.parse(req, {
208 verifySecret: process.env.COMPOSIO_WEBHOOK_SECRET,
209 });
210 if (event.userId !== 'user_123' || event.triggerSlug !== 'GMAIL_NEW_GMAIL_MESSAGE') {
211 return new Response(null, { status: 202 });
212 }
213 await send(
214 `A verified Gmail event arrived. Ask whether I want to inspect the email. ` +
215 `Do not call tools in this turn. Event reference: ${event.uuid}.`,
216 {
217 auth: {
218 authenticator: 'composio-webhook',
219 principalType: 'service',
220 principalId: event.userId,
221 attributes: { triggerSlug: event.triggerSlug },
222 },
223 continuationToken: event.uuid,
224 }
225 );
226 return new Response(null, { status: 202 });
227 }),
228 ],
229 });
230 ```
231
232 If the user continues, the agent can fetch the email in a separate turn and require approval before any side effect. A few more patterns worth wiring up with the same gate:
233
234 - **Stand-up nudge.** A calendar event ten minutes out texts you the agenda and the meeting link, pulled straight from the invite.
235 - **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.
236 - **Money in.** A successful Stripe payment texts you the amount and the customer, no dashboard required.
237 - **Cover for me.** A Slack mention while you're away texts a teammate and asks them to take a look.
238
239 Use the exact slug from the Composio triggers catalog for each. Signature verification proves the event came through Composio; it does not make an email subject, issue title, or other third-party text trustworthy. Reject unexpected users and trigger slugs, keep external content out of the initial prompt, and require approval before side effects such as sending a message.
240
241 ## Browse the project
242
243 The key files, in one place. The local toolkit and the session wiring carry the integration, the eve provider is imported from `@composio/experimental/eve`, and the rest is local macOS glue.
244
245 <RepoBrowser
246 source="imessage"
247 caption="a slice of the real project; the Composio files do the work"
248 heightClass="min-h-[420px] max-h-[640px]"
249 />
250
251 The complete, runnable project will be published in the Composio examples repo.
252
253 ## Run it
254
255 The browser above is an implementation slice, not a standalone fixture: it omits the project's package manifest and supporting `handles`, `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`.
256
257 <Cards>
258 <Card
259 title="eve provider"
260 href="/docs/providers/eve"
261 description="EveProvider, the defineComposioTools resolver, and the (ctx, next) hooks."
262 />
263 <Card
264 title="Local tools and toolkits"
265 href="/docs/extending-sessions/local-tools-and-toolkits"
266 description="Build and register your own in-process Composio tools."
267 />
268 </Cards>