Wellsaid

Empathy. Upgraded.

#ai-assistant #empathy #khoj #llm #mental-health-tech #natural-language-processing #openai #self-hosted #sqlite #svelte

WellSaid

Empathy. Upgraded.

WellSaid helps you communicate with more empathy and clarity by offering iMessage conversation summaries and tone-based reply suggestions.

Features
Getting Started
Usage
How It Works
Technical Details
Development and Local Usage
Accessing from Anywhere
iOS Home Screen Icons (and HTTPS Gotchas)
Troubleshooting
Acknowledgements
Box Art
Screenshots
Contributing
License

Features

Conversation Summaries: Analyze and summarize your Apple iMessage conversations with a specified person from the last 1-24 hours
Smart Reply Suggestions: Get short, medium, and long AI-generated reply options based on recent and and historical conversation context
Tone Selection: Set the tone for your replies with (eg: gentle, funny, reassuring, concise)
Context Addition: Add additional context to help generate more relevant replies
Message Database Integration: Connects to your macOS Messages app database

Getting Started

Requirements

iMessages database access -- designed to run from a Mac logged into your iCloud
API key from OpenAI, Anthropic, or Grok, or a local Khoj instance

Installation

Clone the repository

git clone https://github.com/splinesreticulating/WellSaid.git
cd WellSaid

Install dependencies

yarn install

Generate SvelteKit types (required for testing)

yarn prepare

Configure environment variables

cp .env.example .env

Update the values in the .env file. The following variables are needed:

Logging
- LOG_LEVEL: Logging level (info, debug, warn, error)
Remote Access
- ALLOWED_HOST: For remote access via Tailscale (see 'Accessing from Anywhere' below) -- leave blank or set to 'all' if you don't need access from outside your local network
Security
- APP_USERNAME: A name of your choosing
- APP_PASSWORD: A passowrd of your choice
- JWT_SECRET: A big, long, hard, random, and unpredictable string. You can generate one using OpenSSL with the following command in your terminal:
```
openssl rand -base64 64
```
- Copy the output of this command and use it as the value for JWT_SECRET in your .env file. Ensure it's on a single line.

Start the development server

yarn dev

The server will run over HTTP by default. If you place cert.pem and key.pem in a .certs directory at the project root (see the HTTPS section below), it will automatically use those files and start with HTTPS. Pretty cool.

Usage

Select a time frame to summarize
Choose a tone for reply suggestions
Click "go" to generate a conversation summary and some suggested replies of varying length
Copy your preferred reply to paste into the conversation

How It Works

WellSaid connects to your macOS Messages database to fetch your conversations with a specific contact. It then uses an AI provider (any combination of OpenAI, Anthropic, Grok, and/or Khoj) to analyze the conversation and generate:

A summary of the conversation, including emotional tone and key topics
Three suggested replies (short, medium, and long) in your chosen tone

Technical Details

Minimal Dependencies and Efficient Architecture

WellSaid is built with a focus on minimalism and efficiency:

Core Dependencies: Uses only essential libraries for its functionality
Frontend: Built with SvelteKit, providing excellent performance without the overhead of larger frameworks
Backend: Lightweight Node.js server with minimal dependencies
Database: Direct integration with macOS Messages database - no additional database required
Authentication: Simple JWT-based authentication system

This approach results in a lightweight, fast application that runs efficiently on macOS systems while maintaining all core functionality.

Frontend: Svelte 5 with SvelteKit
State Management: Svelte's built-in $state system
Styling: Custom CSS with variables for theming
Database: SQLite (connecting to macOS Messages database)
AI Integration: OpenAI API (GPT-4 or other models), Anthropic Claude models, Grok, and/or local Khoj server
Logging: Pino for structured logging

Development and Local Usage

# Install dependencies first
yarn install
yarn prepare

# Run in development mode with hot-reloading
yarn dev

# Lint code
yarn lint

# Format code
yarn format

# Build optimized version
yarn build

# Run the optimized build locally
yarn preview

# Run tests
yarn test

# Run tests with watch mode
yarn test:watch

# Run tests with coverage report
yarn test:coverage

Note: Since this application only runs on macOS and accesses local system resources, there is no traditional "production deployment" - the built version is simply run locally on your Mac. The yarn build and yarn preview commands create and run an optimized version that may provide better performance than development mode.

Accessing from Anywhere

If you'd like to securely access WellSaid remotely, use Tailscale to set up a secure private network that connects your devices.

Once your Tailscale network is set up, all that's required in the app is that you set the ALLOWED_HOST variable in your .env file to the address provided by Tailscale. For more details, visit Tailscale's documentation.

iOS Home Screen Icons (and HTTPS Gotchas)

To make your WellSaid app look great when saved to your iPhone's Home Screen, iOS requires a valid HTTPS certificate. This step is optional—if you just want to run the app locally in a browser, you can skip it and use plain HTTP.

Install mkcert (if not already installed)

brew install mkcert
mkcert -install

Generate a local trusted cert and run your app with HTTPS

mkcert <your-tailscale-hostname>.<tailscale-subdomain>.ts.net localhost

This will create a cert/key pair like rootCA.pem and rootCA-key.pem. Move the generated certificate files into a .certs directory at the project root so the development server can automatically find them.

Trust the cert on your iPhone

Convert the root CA to iOS-compatible format:

openssl x509 -inform PEM -in "$(mkcert -CAROOT)/rootCA.pem" -outform DER -out mkcert-rootCA.cer

AirDrop or email the mkcert-rootCA.cer file to your iPhone
Open it, then go to:
- Settings → General → VPN & Device Management → Install Profile
- Settings → General → About → Certificate Trust Settings → Enable full trust for mkcert root

Now when you visit your app over HTTPS (via Safari), iOS will trust the cert, and your manifest and icon will load properly — giving your app a real custom icon when added to the Home Screen.

Privacy and Security Considerations

All conversation analysis happens through the selected AI provider (OpenAI, Anthropic, Grok, or Khoj), so your data is subject to that provider's privacy policy.

Troubleshooting

Common Issues

0 Messages Found: Open the Messages app on your Mac and sign in if you haven't already. Summaries and replies will be available once you've signed in and your partner has sent at least one message.
Messages Not Loading: Ensure you've set your partner's phone number correctly under the Settings tab.
Permission Issues: WellSaid needs access to your Messages database. Make sure Terminal/your editor has Full Disk Access in System Preferences > Security & Privacy.
Go Button Disabled: Conversation summaries are only available when your partner has responded in the selected time frame.