Friends & Session Sharing
Relevant source files
The following files were used as context for generating this wiki page:
- apps/server/docker/sources/app/social/friendAdd.ts
- apps/server/docker/sources/app/social/presenceTracker.ts
- apps/web/react/sources/app/%28app%29/friends/index.tsx
- apps/web/vue/src/composables/useFriends.ts
- apps/mobile/android/app/src/main/res/values/strings.xml
- apps/web/react/sources/text/_default.ts
- packages/schema/protocol/CLAUDE.md
Introduction
The Friends & Session Sharing system is a core social module within the Magic-Agent ecosystem, designed to facilitate collaboration and real-time interaction between users. It allows users to manage a list of trusted contacts through a request-and-approval workflow, track the online presence of their friends, and securely share active AI terminal sessions.
The system is built on a zero-knowledge architecture where session data remains end-to-end encrypted. Friends can see when their contacts are online or actively engaged in a session, and depending on permission levels, can view or interact with shared terminal outputs. This enables collaborative debugging and remote assistance while maintaining strict privacy controls via user-configurable settings.
Sources: apps/server/docker/sources/app/social/friendAdd.ts, apps/web/react/sources/text/_default.ts:474-525
Social Infrastructure & Relationship Management
The social system manages user relationships through a multi-state lifecycle. Relationships are typically initiated via username search or QR code scanning.
Relationship Lifecycle
Relationships progress through several defined statuses:
- Requested: An outgoing friend request sent by the user.
- Pending: An incoming friend request awaiting the user's approval.
- Friend: A mutual connection established after acceptance.
- Rejected/Blocked: A terminated or restricted relationship state.
Sources: apps/web/vue/src/composables/useFriends.ts:98-106, apps/web/react/sources/text/_default.ts:509-514
Data Flow: Adding a Friend
The process of establishing a connection involves a server-side action that validates the existence of both users and ensures they both have required integrations (such as GitHub) connected for identity verification.
Presence Tracking
The system tracks user activity in real-time to inform friends of availability. This includes online status (connected/disconnected) and specific activity types, such as being "In Session."
Presence States
| Status | Description |
|---|---|
| Online | User is currently connected to the Happy server. |
| Offline | User is disconnected; system displays "last seen" timestamp. |
| Away | User is connected but inactive. |
| In Session | User is actively using a Claude Code or Codex terminal. |
Sources: apps/server/docker/sources/app/social/presenceTracker.ts, apps/mobile/android/app/src/main/res/values/strings.xml:214-220
Presence Privacy Controls
Users can toggle their visibility through privacy settings. If "Show Online Status" is disabled, the user appears offline to all friends regardless of actual connectivity.
Sources: apps/web/react/sources/text/_default.ts:420-425, apps/mobile/android/app/src/main/res/values/strings.xml:258-261
Session Sharing
Session sharing allows a user (the host) to grant a friend (the guest) access to an active AI terminal session.
Sharing Permissions
When sharing a session, the host must specify a permission level:
- View Only: The guest can see the message history and real-time updates but cannot send messages.
- View & Chat (Interact): The guest can participate in the conversation and send inputs to the AI agent.
Sources: apps/web/react/sources/text/_default.ts:634-637, apps/mobile/android/app/src/main/res/values/strings.xml:240-244
Sharing Mechanism
Sharing can be implemented via direct friend selection or Link Sharing.
- Direct Share: Adding specific friends to a "People with Access" list.
- Link Sharing: Enabling a unique URL that anyone with the link can access (optionally protected by a password).
API Interface Summary
The following table summarizes the key API endpoints used for friend and social management.
| Endpoint | Method | Description |
|---|---|---|
/v1/friends | GET | Fetches the full list of friends and pending requests. |
/v1/friends/add | POST | Sends a friend request to a user ID (uid). |
/v1/friends/remove | POST | Removes a friend or cancels a pending request. |
/v1/friends/block | POST | Blocks a user from sending future requests. |
/v1/users/search | GET | Searches for users by username string. |
/v1/sessions/:id/share | POST | Configures sharing settings for a specific session. |
Sources: apps/web/vue/src/composables/useFriends.ts:133-255, apps/web/react/sources/text/_default.ts:630-650
Conclusion
The Friends & Session Sharing system provides a secure, collaborative layer for the Magic-Agent platform. By combining robust relationship management with granular permission-based session access and real-time presence tracking, it enables users to work together on AI-assisted coding tasks while maintaining individual privacy and data security through end-to-end encryption.