Suitemates

Architecture
Webpage
Dean Avatar
Penny Avatar
Sunny Avatar
Form page for Dean
Form page for Sunny
Form page for Penny

Inspiration

College life runs on three things that constantly collide: school, money, and friends. You say yes to a weekend beach trip, only to realize it costs money you don't have and lands on the morning of a midterm. The tools that help with each of these live in separate apps, and nobody opens five apps to plan a Saturday.

We wanted help that feels less like software and more like friends in your messages. You just text them, they reach out first when something matters, and they coordinate with each other so you never have to be the go-between.

What it does

Suitemates gives every UNC student three AI agents who live in iMessage, each with its own phone number and personality. Dean handles school: he reads Canvas, tracks deadlines, quizzes and exams, and tells you how a missed assignment would move your grade. Penny handles money: she watches your bank account, reacts to new purchases, tells you whether you can afford something, and points out spending habits and cheaper swaps. Sunny handles plans: she finds people who want to do what you want to do, from student-made plans to real UNC events pulled live from Heel Life, ranked by your interests.

Getting started takes seconds. You scan an agent's QR code on our website, fill in a short form, and that agent texts you first from its own number. If you text Sunny without signing up, she sets you up herself by asking your name and what you're into, with no money questions.

The agents work as a team. Tell Sunny you're going on the beach trip Saturday and she adds you, tells you who else is going, and asks whether Penny and Dean should weigh in. Say yes, and both text you from their own numbers: Penny checks the cost against your budget, and Dean warns you about the midterm that same morning. When someone else joins your plan later, Sunny lets you know.

Everything connects behind the scenes. The agents share one memory, so telling any of them you don't have a car or that you're vegetarian means all three remember. A private calendar link puts Dean's deadlines and Sunny's plans side by side in Google or Apple Calendar. And they stay honest: agents only state facts their tools return, the system blocks any claim that another agent is texting you unless it really is, and Penny only prices plans she has a real cost for, and when an agent is working from sample data rather than your real Canvas or bank account, it says so.

How we built it

Suitemates runs on a single TypeScript and Node.js server that powers all three agents. Each agent is a self-contained module with its own prompt, personality, and tools, and a shared engine handles messaging, memory, sign-up, the calendar feed, and agents bringing each other into a conversation. The reasoning comes from Google Gemini with function calling, so every answer is grounded in a tool result rather than a guess.

Messaging runs on Photon's iMessage platform, with each agent on its own Photon project and phone number; signing up through an agent's QR code adds you to that agent's project automatically. Dean reads Canvas, Penny reads Capital One's Nessie banking sandbox, and Sunny combines a shared sign-up board with UNC's Heel Life event feed, cached so we stay polite to their servers. The landing and sign-up pages are hosted on Vercel and reach our server through a Cloudflare tunnel, and a watchdog alerts us if anything breaks while judges are using it.

We treated quality as part of the product. The codebase has more than 270 automated tests, each written to fail before the fix that makes it pass, and every feature went through an adversarial review before merging. We also tuned each agent's voice to text like a student, capped at one emoji per message, so they read like friends rather than notifications.

Kerry built the shared engine, Penny, and the deployment; Ismail built Dean, the sign-up flow, and the agents' personalities; Abdullah built Sunny, including matching, live campus events, the shared calendar, and her onboarding. In line with MLH's AI policy: we used Claude Code to help write code across the project, Gemini powers the agents at runtime, and our avatars were generated with Z-Image-Turbo. The README has full details.

Challenges we ran into

Giving each agent its own number was harder than expected. Photon assigns numbers from a shared pool and only answers people on each project's invite list, so our first sign-up flow added everyone to Dean's project and the other agents' numbers refused to recognize them. We moved to one Photon project per agent and made every QR code add students to the right one.

Group chats were our original plan, but our Photon tier cannot create them. We replaced the idea with agents recruiting each other in direct messages, which turned out to feel more natural, since each agent speaks from its own thread. We also ran into Gemini's free-tier limits mid-test, moved to a paid key, and benchmarked the models: the fastest one claimed to complete actions it never actually performed, so we chose reliability over speed.

The subtler problems were about trust. Dates like "Sunday 4-6 PM" or "tomorrow at 3pm" had to land on the right calendar day and stay there. In one early test, Sunny promised a student she would invite friends she had no way to contact, which taught us that an agent should only offer what its tools can actually deliver.

Accomplishments that we're proud of

Suitemates works end to end over real iMessage. A student can scan a QR code, receive a text from their own agent, and watch two more agents join the conversation from their own numbers when Sunny brings them in. The data is real as well: live UNC events from Heel Life, a working bank sandbox, and Canvas for anyone who connects their account.

We are especially proud of the hand-off moment, where a single message about a beach trip becomes a price check and a midterm warning without opening another app. We also shipped as a team: three people merged into one codebase through the night, with every merge passing the full test suite and every feature reviewed before it landed.

What we learned

An agent is only as trustworthy as its tools. The most important design decisions were about what agents are not allowed to say, and those rules had to live in code as well as in prompts. We also learned that model choice is about reliability as much as speed, and that infrastructure choices, like one shared number versus a number per agent, can reshape the entire product.

What's next for Suitemates

With dedicated phone numbers, Sunny could create group chats herself and introduce students she has matched. We want friends' agents to coordinate with each other, so you could ask Sunny when a friend is free this weekend, and we want Sunny to invite students who opt in to plans that fit their interests. Longer term, we plan to add more campus data such as dining and recreation hours, support official Heel Life RSVPs from inside the chat, and open Suitemates to every UNC student.