terminalplugin.ts
$ git clone https://github.com/l2succes/claire.git
$ cd claire && bun run setup
✓ wrote .env · PLATFORM_MODE=mock
$ bun run dev
✓ server http://localhost:3001
✓ mobile expo · press i for iOS
$ ▍Open product reference
Build the place
where conversations
do things.
Claire is an AI-native, multi-network messenger with open references for mobile, desktop, connectors, and conversation plugins. Clone it, run the whole stack in mock mode, and make one part dramatically better.
- +10 in the catalog
bun test examples/plugins12 pass · 0 fail
Plugin approvedcalendar.events.create · receipt written
RUN IT LOCALLY
The whole stack,
in four commands.
Setup writes local environment files and starts in mock mode, so the first run needs no WhatsApp session, no Supabase project, and no API keys.
- 1Clone and install
git clone https://github.com/l2succes/claire.gitBun workspaces cover mobile, desktop, server, website, packages, and examples.
- 2Generate local config
bun run setupWrites .env files and selects mock mode for the messaging platform.
- 3Run server and mobile
bun run devBun API on port 3001 plus the Expo client, watching in parallel.
- 4Prove it works
bun run test:pluginsFixture-backed plugin tests run without a network call.
SYSTEM ARCHITECTURE
One message plane.
Many product surfaces.
Claire normalizes network events through Matrix, stores user-owned product state, and exposes one authenticated API to mobile, desktop, automation, and AI.
CLIENTS
Expo mobileReact Native macOSWeb referencesCLAIRE CORE
Bun API · :3001Policy, queues, receiptsProvider-neutral AI layerPlugin runtimeDATA PLANE
Synapse + mautrixSupabase · PostgresRedis sessionsONE MESSAGE, END TO END
The path every inbound message takes before a client renders it.
- 01Network eventWhatsApp, Telegram, or Instagram emits a message.
- 02mautrix bridgeThe bridge translates it into a Matrix room event.
- 03Event converterClaire normalizes it into a UnifiedMessage.
- 04Postgres + realtimeUpserted on the platform message id, then broadcast.
- 05Every clientMobile, desktop, and the AI layer read the same record.
PLUGIN SDK
Typed actions.
Visible permissions.
A plugin declares what it can do, how risky each action is, and whether a person has to approve it. Claire refuses to load an action without a handler.
calendar/src/index.ts@claire/plugin-sdk
TYPESCRIPTimport { definePlugin } from '@claire/plugin-sdk';
export const calendarPlugin = definePlugin({
manifest: {
id: 'com.claire.example.calendar',
capabilities: [{
id: 'calendar.events.create',
kind: 'action',
risk: 'low_write',
approval: 'always',
reversible: true,
}],
triggers: [{ event: 'schedule.detected' }],
},
handlers: {
async 'calendar.events.create'(request) {
return { ok: true, receiptId: createReceiptId() };
},
},
});THE RISK LADDER
Every capability declares one of four levels. The level sets the default approval.
readapproval: neverReads context only. No side effects to undo.low_writeapproval: configurableWrites inside Claire. Reversible and idempotent.external_writeapproval: alwaysTouches a third-party system a person can see.destructiveapproval: alwaysCannot be undone. Needs an explicit human yes.
CLAIRE WANTS TO RUN AN ACTIONCreate “Design review” · Thu 11:00
- Plugin
- Example Calendar · community
- Risk
- low_write · reversible
- Reads
- This thread only
Always allow
PRODUCT REFERENCES
See the whole system before touching a screen.
These pages are living references, not frozen handoff files. Update the relevant reference alongside meaningful UI or behavior changes.
9:41
Good morning.
Three conversations need you.
Mobile app reference
Core loop, Ask Claire, inbox, promises, people, memory, settings, and setup states.
Open 14+ screensDesktop app reference
Unified workspace, companion behavior, connections, Ask Claire, and component states.
Open desktop systemPlugin library reference
Discovery, permissions, automation builder, approvals, receipts, and developer trust.
Open plugin systemAaInter · DM Mono
Contributor documentation
Repository setup, architecture, plugins, testing, contribution workflow, and roadmap.
Open docsBUILD CLAIRE
Choose a contribution lane.
The best first contribution is a narrow, testable improvement with a clear user outcome—not a new abstraction searching for a problem.
01
Mobile experience
Expo Router screens, conversation interaction, accessibility, and design-system primitives.
Open mobile/02
Desktop client
React Native macOS, keyboard-first workflows, local bridge health, and dense workspace patterns.
Open desktop/03
Messaging connectors
Matrix event normalization, authentication, sync recovery, media, and network capability definitions.
Read the roadmap04
AI and plugins
Provider-neutral inference, Ask Claire, typed tools, permissions, approvals, and auditable automation.
Read the plugin guide- 1Run locallyConfirm the existing behavior first.
- 2Find the referenceMatch the product language already in use.
- 3Build the smallest sliceInclude the empty, error, and offline states.
- 4Prove itAdd a test and update the reference you changed.
DEVELOPER COMMUNITY
Build in public.
Operate with care.
The community can make Claire broader and more trustworthy: connectors for underserved networks, local-first deployments, plugins for real workflows, translations, accessibility, and deeper platform-native experiences.