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 contact 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

1. Clone the repository

git clone https://github.com/artificial-eq/WellSaid.git
cd WellSaid

2. Install dependencies

yarn install

3. Generate SvelteKit types (required for testing)

yarn prepare

4. 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.

5. 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

1. Select a time frame to summarize
2. Choose a tone for reply suggestions
3. Click "go" to generate a conversation summary and some suggested replies of varying length
4. 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 (Khoj, OpenAI, Anthropic, or Grok) to analyze the conversation and generate:

1. A summary of the conversation, including emotional tone and key topics
2. 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.

iPhone 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.

1. Install mkcert (if not already installed)

brew install mkcert
mkcert -install

2. 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.

3. 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 contact has sent at least one message.
• Messages Not Loading: Ensure you've set the correct phone number for your contact in Settings
• Permission Issues: WellSaid needs access to your Messages database. Make sure your terminal and/or editor app has Full Disk Access in System Preferences > Security & Privacy.
• Go Button Disabled: Conversation summaries are only available when your contact has responded in the selected time frame.

Acknowledgements

• Svelte - The web framework used
• OpenAI - AI model provider
• Anthropic - Claude model provider
• Grok - Additional AI provider option
• Khoj - Alternative local AI model provider and search
• SQLite - Database engine
• Tailscale - For making secure remote access easy

Box Art

Screenshots

Desktop

Mobile

Contributing

Feel free to submit a pull request or open an issue if you find a bug or have a feature you'd like to add.

License

This project is licensed under the MIT License. See?