# boop-agent turns iMessage into the front end of a Claude or Codex agent

> boop-agent is a personal agent you talk to over iMessage, backed by either the Claude Agent SDK and your local Claude Code login or the local Codex app-server runtime and your codex login, so no separate provider API key is needed. The architecture is a dispatcher that spawns focused sub-agents, a three tier memory store on Convex, automations, a draft-and-send rule for external actions, and a React debug dashboard, and the author is explicit that it is a template rather than a product.

**raroque/boop-agent** — iMessage personal agent: choose Claude Agent SDK (Claude Code) or Codex app-server runtime (Codex/ChatGPT), with memory, sub-agents, automations, integrations.

- Repository: https://github.com/raroque/boop-agent
- Stars: 1,387 · Forks: 299
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/raroque-boop-agent

## The runtime is the subscription you already have

The project is described as an iMessage-based personal agent you can run with either your Claude Code subscription or your Codex and ChatGPT subscription, and the runtime is chosen during setup. The Claude path is powered by the Claude Agent SDK and your local Claude Code login. The Codex path is powered by the local Codex app-server runtime and your local codex login. The point of that choice is stated plainly, that no Anthropic or OpenAI API key is required for the agent runtime when using subscription auth, which means the agent runs on a plan you are already paying for rather than on a metered API bill. The environment file shows the switch, a BOOP_RUNTIME value that is claude or codex, and the model settings for each path, with a Claude model default and a Codex model default plus a reasoning effort setting. The Codex path expects codex login on the host, and there is an override to point at a different Codex home if the auth file lives elsewhere.

## iMessage in, iMessage out, through a webhook bridge

The message path runs through Sendblue, which is free on their agent plan, and the repository has scripts for each side of it. The inbound side is a webhook, with signed inbound requests, typing indicators and webhook dedup, and the Sendblue CLI integration is designed so that npm run dev auto-registers the inbound webhook for you on every restart, which removes the need to re-paste a URL into the dashboard when a free ngrok URL rotates. The outbound side is the API, and the environment file is careful about one detail, that SENDBLUE_FROM_NUMBER must be the Sendblue-provisioned number, the one people text to, and not a personal cell number, because the Sendblue API requires it. The naming has a story behind it. Boop is meant to be a proactive agent, one that nudges you over iMessage with reminders, drafts and little follow-ups, a small boop whenever it has something for you, and it is named after the author's dog Luna.

## A dispatcher that is denied the interesting tools

The architecture diagram is the most instructive part of the README:

```text
 iMessage  →  Sendblue webhook  →  Interaction agent  →  Sub-agents (per task)
                                          │                    │
                                          ▼                    ▼
                                    Memory store  ←──  Integrations (your MCP tools)
```

The pattern is a dispatcher and workers. A lean interaction agent decides what to do and spawns focused sub-agents that actually do the work. And the dispatcher is deliberately restricted, because in the pure dispatcher mode the interaction agent has only memory, spawn, automation and draft tools, and web access, files and integrations are explicitly denied to it, while the sub-agents get WebSearch, WebFetch and the integrations. The reasoning is straightforward once stated. The agent that talks to you should not be the agent with a browser and a hundred API credentials, so the permissions are split along the trust boundary rather than given to the whole thing.

## Memory in three tiers, with a consolidation job that argues

The memory system is tiered, with short, long and permanent tiers, post-turn extraction, decay and cleaning. Recall is vector search with a local BGE-large fallback, or optional Voyage and OpenAI embeddings. The most interesting component is memory consolidation, a daily three-phase adversarial pipeline of proposer, adversary and judge that merges duplicates, resolves contradictions and prunes noise, using the configured runtime with provider-specific model defaults, running every 24 hours by default and also triggerable manually through a POST to /consolidate. The adversarial framing is the point. A single summariser that merges memories will happily overwrite a fact with a newer wrong one, so a second pass tries to break what the first pass proposed and a third judges between them. The dashboard shows the result as a force-directed graph of clustered memories across the three tiers, with a tabular view as well.

## Automations, and the rule that nothing is sent without a confirmation

Two features define the agent's behaviour in a way that is easy to describe and hard to build. The first is automations, where the agent can schedule recurring work from a plain sentence such as every morning at 8 summarize my calendar, and push the results back to iMessage, and the dashboard's Automations tab shows them running. The second is draft-and-send, and the rule is absolute: any external action stages a draft first, and the agent only commits when the user confirms. That single constraint is what separates an assistant from an agent with a Gmail integration and a Stripe key, and it is enforced in the design rather than left to a prompt. Around those two there is the rest of the operational surface, a heartbeat and retry so stuck agents auto-fail and the debug dashboard can retry them, an optional local browser use mode backed by a Patchright Chrome profile for login-required services and visual workflows, and optional read-only Mac connectors for iMessage, Apple Notes and Apple Reminders that stay off until you enable them.

## The stack, and a dashboard that makes the agent inspectable

The components are named with their roles. Convex is the real-time, typed database for memory, agents and drafts, with a free tier, and the environment file says to run npx convex dev to create a project and populate the local environment. Composio is the integrations layer, where one API key connects Gmail, Slack, GitHub, Linear, Notion, Drive, HubSpot and a thousand more with hosted OAuth and token refresh handled for you, and the dashboard's Connections tab is where you click Connect. The debug dashboard itself is a React and Vite application, with tabs for usage, known cost, tokens and agent status, an Agents view that shows every spawned sub-agent with its status, usage and cost, tokens, turns, runtime and the integrations it touched, plus Automations, Memory, Events and Connections. The desktop shell is Electron, and the package scripts show the whole development surface, with dev, dev:parallel for the server, Convex and dashboard together, a preflight check, an Electron pack and dist, and a codex:protocol script that generates the TypeScript types for the Codex app-server protocol.

## The author says it is not a product, and that matters

There is a section headed Heads up before you use this, and it is worth quoting rather than paraphrasing. This was never meant to be open-sourced, it was built for personal use and the architecture was shared after enough people asked, and it is not a product. It is not optimized for cost or security, the advice is to use it at your own risk, review the code, set your own budgets, and not to trust it with anything you would not trust yourself with. The project is also framed as a starting point rather than a finished product, an architecture opened up as a template to take, text-enable and extend, with integrations plugged in through Composio. The repository says that pull requests for optimizations are welcome, including performance, bug fixes, developer experience, new example integrations and better docs. The version in the package metadata is 0.2.0 and the package is marked private, the last push was on 2026-07-13, and there are no GitHub releases, so this is a snapshot of somebody's working setup rather than a maintained distribution.

## Conclusion

boop-agent is worth reading if you want to build a personal agent that you already pay for through a coding subscription, because it shows a working division of labour between a lean dispatcher and focused sub-agents, and it shows the parts that are usually omitted, the memory consolidation, the draft-and-send gate and the debug dashboard that makes an agent's behaviour inspectable. It is not something to run on a shared account or with data you care about, and the author says so himself, with the project never meant to be open-sourced, not optimized for cost or security, and to be used at your own risk after review. Before you deploy it, read ARCHITECTURE.md and INTEGRATIONS.md, set your own budgets in the dashboard, and remember that the credentials in the environment include a Sendblue API secret and Composio OAuth tokens for every connected service.

## FAQ

### What runtime does boop-agent use?

You choose during setup between the Claude path, powered by the Claude Agent SDK and your local Claude Code login, and the Codex path, powered by the local Codex app-server runtime and your local codex login. The BOOP_RUNTIME environment variable selects which one is used, and no separate provider API key is required when you authenticate with the subscription.

### How does the interaction agent differ from the sub-agents?

The interaction agent is a lean dispatcher with only memory, spawn, automation and draft tools, and web access, files and integrations are explicitly denied to it. The sub-agents it spawns are the ones that get WebSearch, WebFetch and the Composio integrations, so the agent you talk to is not the one holding the credentials.

### How does boop-agent remember things?

With tiered memory across short, long and permanent tiers, post-turn extraction, decay and cleaning, and vector search for recall with a local BGE-large fallback or optional Voyage and OpenAI embeddings. A daily three-phase consolidation pipeline of proposer, adversary and judge merges duplicates, resolves contradictions and prunes noise, and it can also be triggered manually with POST /consolidate.

### What happens before the agent sends anything on your behalf?

Any external action stages a draft first, and the agent only commits when the user confirms. The debug dashboard shows the drafts, the sub-agents with their status, usage and cost, the automations that ran, and the Composio connections that are live.

## Sources

- [Issues](https://github.com/raroque/boop-agent/issues)
- [License: MIT](https://github.com/raroque/boop-agent/blob/main/LICENSE)
- [raroque/boop-agent on GitHub](https://github.com/raroque/boop-agent)
- [README](https://github.com/raroque/boop-agent/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/raroque-boop-agent