language

An iMessage language-learning buddy

2 min

Texts you like a bilingual friend. It chats mostly in your native language and naturally sprinkles in the language you're learning — picking words and phrases that fit the conversation, glossing what you don't know, gently modeling corrections, and remembering things about you across chats. No app, no lessons. Just a thread.

It reuses the self-hosted iMessage transport (forked from the marco/Bedrock stack): a dylib injected into Messages.app for sending + typing dots + read receipts, and a chat.db poller for inbound. The language-buddy agent loop is built on top.

Layout

Path	What it does
config.mjs	languages, level, model, whitelist (reads .env)
server.mjs	wires poller → agent → helper (run this)
core/agent.mjs	persona + Claude call + remember tool → reply bubbles
core/memory.mjs	per-handle profile + rolling conversation (.memory.json)
imessage/	ported transport (poller, helper, injected dylib) — unchanged

Setup

1. .env (already present, ported from marco). Needs your Anthropic key, plus any product knobs you want to override:

   ANTHROPIC_API_KEY=sk-ant-...
   TARGET_LANGUAGE=Korean       # the language you're learning  (default: Korean)
   NATIVE_LANGUAGE=English      # what the buddy mostly speaks   (default: English)
   LEVEL=beginner               # beginner | intermediate | advanced
   AGENT_NAME=Lingo             # the buddy's name
   MODEL=claude-opus-4-8        # snappier/cheaper: claude-sonnet-4-6
   # ALLOW_FROM=you@icloud.com  # optional: only engage these handles

2. One-time host setup for the injected dylib (SIP off, library validation off, arm64e preview ABI). See imessage/README.md.
3. Agent identity — sign Messages.app on the Mac into a separate Apple ID so you can text it from your own phone (see marco's DESIGN.md for the why/how).

Run

npm install
npm run messages   # terminal 1: launches Messages.app with the helper injected
npm start          # terminal 2: listens for the helper, polls chat.db, replies

Text the agent's Apple ID from your iPhone. You'll see read receipts, typing dots, and a few short bubbles back.

Notes

• Model / latency
  Defaults to Opus 4.8 with thinking off + low effort for snappy, text-message-style replies. For a faster/cheaper buddy, set MODEL=claude-sonnet-4-6.
• Memory
  Lives in core/.memory.json (gitignored), keyed by handle. Delete it to start fresh. The buddy writes to it via its remember tool.
• Tuning the buddy
  All in core/agent.mjs (buildSystemPrompt). That's the make-or-break — if the conversation feels good, the rest follows.