<div align="center"> <img src=".github/openscribe-banner.png" alt="OpenScribe Banner" width="5%" />

OpenScribe

Open-source AI medical scribe for recording encounters and generating structured clinical notes.

<p> <a href="https://github.com/sammargolis/OpenScribe/blob/main/LICENSE"> <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="MIT License"> </a> <a href="https://discord.gg/BcNNspcNE8"> <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"> </a> <a href="https://www.loom.com/share/1ccd4eec00eb4ddab700d32734f33c28"> <img src="https://img.shields.io/badge/Demo-Watch-000000?style=for-the-badge" alt="Demo"> </a> </p> </div>

Project Overview

OpenScribe is a free, MIT-licensed, open-source AI medical scribe that helps clinicians record patient encounters, transcribe audio, and generate structured draft clinical notes using LLMs. The default web deployment path is mixed mode: local Whisper transcription + Anthropic Claude note generation. A fully local desktop path is also available, forked from StenoAI.

• Demo
• Architecture
• Contributing
• Download and Use Desktop
• Desktop Release Runbook

OpenScribe is not HIPAA compliant yet. The team is actively working toward HIPAA compliance.

Demo

Demo

Star History

<a href="https://www.star-history.com/?repos=Open-scribe%2FOpenScribe&type=timeline&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Open-scribe/OpenScribe&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Open-scribe/OpenScribe&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/image?repos=Open-scribe/OpenScribe&type=timeline&legend=top-left" /> </picture> </a>

Download Desktop App (No Dev Setup)

If you only want to try OpenScribe as an app:

1. Open latest releases.
2. Download the installer for your OS/arch.
3. Run installer and complete first-run setup wizard.

Full guide: docs/DOWNLOAD_AND_USE.md

Quick Start (5 minutes)

1. Install Prerequisites

node --version  # Check you have Node.js 18+
# If not installed (macOS): brew install node
# If installed but <18 (macOS): brew upgrade node
npm install -g pnpm

2. Clone and Install

git clone https://github.com/sammargolis/OpenScribe.git
cd OpenScribe
pnpm install

3. Configure Environment (Mixed Web Default)

Create env defaults:

pnpm run setup  # Auto-generates .env.local with secure storage key

Edit apps/web/.env.local and add:

TRANSCRIPTION_PROVIDER=whisper_local
WHISPER_LOCAL_MODEL=tiny.en
ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE
# NEXT_PUBLIC_SECURE_STORAGE_KEY is auto-generated, don't modify

OPENAI_API_KEY is optional unless you switch to TRANSCRIPTION_PROVIDER=whisper_openai.

4. Start the App

pnpm dev:local    # One command: Whisper local server + web app

Optional desktop app path:

pnpm electron:dev

Desktop production builds:

pnpm build:desktop:mac
pnpm build:desktop:win
pnpm build:desktop:linux
# or
pnpm build:desktop:all

GA support target for packaged desktop releases:

• macOS (mainstream current) x64, arm64
• Windows (mainstream current) x64
• Linux (mainstream current desktop distros) x64, arm64
• Recommended minimum: 8GB RAM, 20GB free disk

See release gate details in docs/RELEASE_READINESS_CHECKLIST.md. Manual reviewer sign-off template: docs/MANUAL_SIGNOFF_TEMPLATE.md.

Quick Start (Docker)

SAM is the easiest way to run OpenScribe for new contributors: one command starts the web app and local Whisper transcription service.

1. Create SAM env file

pnpm run setup

Edit apps/web/.env.local and set:

ANTHROPIC_API_KEY=sk-ant-YOUR_KEY_HERE

2. Start SAM

docker compose -f docker-compose.sam.yml up --build

3. Open the app

http://localhost:3001

4. Verify Whisper health (optional)

curl http://127.0.0.1:8002/health

---

Runtime Modes

OpenScribe supports three workflows. Mixed web mode is the default path.

Mixed Web (default)

• Transcription: local Whisper server (pnpm whisper:server) with default model tiny.en
• Notes: larger model (default Claude in web path)
• Start everything with one command: pnpm dev:local
• Configure with TRANSCRIPTION_PROVIDER=whisper_local in apps/web/.env.local
• Setup guide

Language support

• Default model tiny.en as well as all .en-models transcribes English only
• Multilingual transcription works for both local and API-based models
• Multilingual transcription is supported by setting WHISPER_LANGUAGE (see .env.local.example for details) and (for local use) switching to a non-.en Whisper model (e.g. tiny, base, small)

Local-only Desktop (optional)

• Transcription: local Whisper backend in local-only/openscribe-backend
• Notes: local Ollama models (llama3.2:*, gemma3:4b)
• No cloud inference in this path
• First-run desktop setup wizard guides Whisper/model downloads
• Setup guide

Cloud/OpenAI + Claude (fallback)

• Transcription: OpenAI Whisper API
• Notes: Anthropic Claude (or other hosted LLM)
• Requires API keys in apps/web/.env.local

OpenClaw + OpenEMR Demo Handoff (desktop)

• The note editor now includes Send to OpenClaw (desktop app path).
• Trigger flow: record encounter -> note appears -> click Send to OpenClaw.
• OpenScribe sends patient/note context to OpenClaw and requests an OpenEMR note action.

Optional environment variables for demos:

# OpenClaw CLI (default: openclaw on PATH)
OPENCLAW_BIN=openclaw

# Target OpenClaw agent/session (default: main)
OPENCLAW_AGENT=main

# If set to 1, OpenClaw can deliver responses to a configured channel
OPENCLAW_DELIVER=0

# Optional webhook transport instead of CLI
# OPENCLAW_DEMO_WEBHOOK_URL=http://127.0.0.1:8787/openscribe/handoff
# OPENCLAW_DEMO_WEBHOOK_TOKEN=your-token

FYI Getting API Keys

OpenAI (transcription): platform.openai.com/api-keys - Sign up → API Keys → Create new secret key

Anthropic (note generation): console.anthropic.com/settings/keys - Sign up → API Keys → Create Key

Both services offer $5 free credits for new accounts

Staying Updated

git pull origin main  # Pull latest changes
pnpm install          # Update dependencies

# If you encounter issues after updating:
rm -rf node_modules pnpm-lock.yaml && pnpm install

---

Purpose and Philosophy

OpenScribe exists to provide a simple, open-source alternative to cloud dependent clinical documentation tools. The project is built on core principles:

• Local-first storage: Encounter data is stored locally in the browser by default
• Privacy-conscious: No analytics or telemetry in the web app; external model calls are explicit and configurable
• Modular: Components can be swapped or extended (e.g., different LLM providers, transcription services)

Local MedGemma (Text-Only) Scribe

This repo now includes a fully local, text-only MedGemma scribe workflow in packages/pipeline/medgemma-scribe. It requires pre-transcribed text and does not perform speech-to-text. See packages/pipeline/medgemma-scribe/README.md for setup and usage.

Project Resources

• GitHub: sammargolis/OpenScribe
• Maintainer: @sammargolis
• Architecture: architecture.md
• Tests: packages/llm, packages/pipeline

Roadmap

Current Status (v0)

• Core recording, transcription, and note generation
• AES-GCM encrypted local storage
• Browser-based audio capture

Near-term (v0.1-0.5)

• Error handling improvements
• Comprehensive test coverage
• Basic audit logging

Physical Controls:

• User responsibility (device security, physical access)

Future Goals (v2.0+)

• Package app to be able to run 100% locally with transcription model and small 7b model for note generation
• Multiple LLM providers (Anthropic, local models)
• Custom note templates
• Optional cloud sync (user-controlled)
• Multi-language support
• Mobile app
• EHR integration
• RCM integration

Architecture

See architecture.md for complete details.

┌─────────────────────────────────────────────────────────┐
│                    UI Layer (Next.js)                   │
│  ┌──────────────┐              ┌─────────────────────┐  │
│  │ Encounter    │              │  Workflow States    │  │
│  │ Sidebar      │◄────────────►│  - Idle             │  │
│  │              │              │  - Recording        │  │
│  │              │              │  - Processing       │  │
│  │              │              │  - Note Editor      │  │
│  └──────────────┘              └─────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Processing P