A private place for the things you don't know how to say out loud.

We all have moments where our thoughts are tangled, emotionally heavy, or too sensitive to share with friends, colleagues, or social media. Most modern AI tools immediately attempt to optimize, diagnose, solve, or extract telemetry to the cloud.

Unsaid takes a completely different path:

1. Prerequisites

• Node.js: v18.0.0 or higher (nodejs.org)
• LM Studio: v0.3.0 or higher (lmstudio.ai)
• Model: Gemma 2 2B Instruct or Gemma 2 9B Instruct (GGUF format)

2. Installation & Launch

# 1. Clone the repository
git clone https://github.com/basutkar/unsaid.git
cd unsaid

# 2. Install dependencies
npm install

# 3. Launch the desktop application
npm run dev
# OR for the standalone window:
npm run desktop

# 4. Launch the interactive CLI shell in another terminal tab:
npm run shell

┌────────────────────────────────┐         ┌───────────────────────────────┐
│     Unsaid Desktop App         │         │      Unsaid CLI Shell         │
│  (React 19 + TypeScript + Vite)│         │     (Node.js Interactive)     │
└───────────────┬────────────────┘         └───────────────┬───────────────┘
                │                                          │
                │  GET/POST /api/reflections               │ Direct Read/Write
                ▼                                          ▼
     ┌─────────────────────────────────────────────────────────────┐
     │           Local File Bridge: ~/.unsaid/reflections.json     │
     │            (Automatic Conflict-Free Bidirectional Sync)      │
     └─────────────────────────────────────────────────────────────┘
                                    ▲
                                    │ Local HTTP Requests
                                    ▼
     ┌─────────────────────────────────────────────────────────────┐
     │             LM Studio Local Inference Server                │
     │         http://localhost:1234/v1/chat/completions           │
     │            (Google Gemma 2 2B/9B Instruct GGUF)             │
     └─────────────────────────────────────────────────────────────┘

Unlike cloud-based chat apps with complex backend servers and user databases, Unsaid writes directly to your local file system at ~/.unsaid/reflections.json. The Vite development server provides a lightweight internal bridge proxy for the browser environment, allowing edits in either the CLI or Desktop to mirror instantly.

Some thoughts are best articulated in long-form prose addressed to someone specific. The Letter Studio provides a focused parchment writing canvas with therapeutic rituals:

• Burn Ritual: A therapeutic animation that permanently shreds the text from memory and disk, symbolizing release.
• Vault: Store encrypted reflections locally behind your optional 4-digit PIN lock.
• Gemma Mirror: Ask Gemma to read your draft and reflect back what emotion seems to be hiding beneath the words.

To create an immersive, calming space without loading external audio assets, Unsaid incorporates a native Web Audio API synthesizer that generates procedural acoustics:

• 🌧️ Gentle Rain: Pink noise filtered through dual bandpass resonant nodes simulating raindrop strikes.
• 🔥 Cozy Fireplace: Low-frequency brown noise mixed with random pop and crackle impulse triggers.
• 🌊 Soft Stream: Smooth high-shelf filtered modulation for focused writing and unburdening.

Unsaid is engineered to communicate with any OpenAI-compatible local server, but is specially tuned with system prompts for Google's open Gemma 2 models:

1. Download LM Studio from https://lmstudio.ai (Windows, macOS, Linux).
2. Open the Search tab in LM Studio and search for: "gemma-2-2b-it" or "gemma-2-9b-it".
3. Download a Q4_K_M or Q5_K_M GGUF quantization.
4. Go to the "Local Server" tab (the <-> icon on the left).
5. Select your loaded Gemma model at the top.
6. Click "Start Server". By default, it runs on http://localhost:1234.
7. Unsaid will immediately detect the server and show a green "Online" indicator!

For developers and terminal lovers, unsaid includes an interactive terminal shell that provides all the power of the desktop app inside your favorite terminal:

# Start the interactive shell
npm run shell

# Or if linked globally:
unsaid

Interactive Shell Commands

Unsaid uses an ultra-low latency file-based bridge stored at ~/.unsaid/reflections.json. When you write in the CLI shell:

1. Your messages and Gemma's streaming tokens write atomically to disk.
2. The Desktop App checks the lightweight file timestamp or receives live updates through the internal API endpoint.
3. New reflections appear automatically with a >_ Shell origin tag in the sidebar.

Speaking thoughts out loud often accesses deeper emotions than typing. Unsaid pairs directly with Handy (cjpais/Handy)—a native, open-source offline speech-to-text tool powered by whisper.cpp and Vulkan:

1. Open Unsaid Desktop App (npm run dev or npm run desktop).
2. Handy Companion runs in the background (or click "Launch Handy" in Unsaid).
3. Press Ctrl + Space to dictate your thoughts out loud.
4. Watch your words stream into the Quick Reflection Composer.
5. Press Ctrl + Enter or click "Talk Through It" to reflect with Gemma 3 4B!

Unsaid actively monitors user input against a comprehensive, compassionate safety evaluation matrix before sending tokens to the local model:

Guardrail Rules:

• No Medical / Diagnostic Claims: The model is constrained to never label symptoms with DSM-5 psychiatric diagnoses.
• No Medication Advice: Unsaid refuses to discuss dosages or prescribe pharmaceuticals.
• Compassionate De-escalation: Responses focus on grounding, breathing exercises, and encouraging real-world human support.

Cloud AI providers log prompts, train on chat transcripts, and are vulnerable to data breaches. With Unsaid:

• Your messages stay strictly in local memory and in ~/.unsaid/reflections.json.
• Network calls only route to http://localhost:1234. Disconnecting your Wi-Fi changes nothing.
• You can set an optional 4-digit PIN lock to prevent shoulder-surfing on shared computers.

Q: The indicator shows "Local Model Offline"

Make sure LM Studio is open, your model is selected, and you have clicked Start Server on port 1234. Verify in your browser by visiting http://localhost:1234/v1/models.

Q: Reflections created in the CLI don't show in the App

Ensure you are running the desktop app with npm run dev or npm run desktop so that the Vite local bridge endpoint is active. The app checks every 3 seconds for updates.