calwash 0.3.0

Redact sensitive data from your calendar events

calwash

Redact sensitive data from your calendar events. Detect and remove PII (phone numbers, emails, SSNs, credit cards), medical terms, legal references, and more — with optional local AI detection that never sends your data to the cloud.

Install

pipx install calwash

Or with pip:

pip install calwash

Quick Start

# 1. Log in to your Google account (opens browser)
calwash login

# 2. Preview what would be redacted
calwash clean --dry-run

# 3. Apply redactions (creates backup first)
calwash clean

What It Detects

Regex (always on):

Pattern	Example	Replaced with
Email addresses	[e-mail]	[EMAIL REMOVED]
Phone numbers	555-123-4567	[PHONE REMOVED]
Social Security Numbers	123-45-6789	[SSN REMOVED]
Credit card numbers	4111-1111-1111-1111	[CARD REMOVED]
URLs	https://zoom.us/j/123	[URL REMOVED]
Medical terms	Dr. appointment at clinic	Private

AI detection (opt-in, local only):

Category	Example
Medical	"Picking up lithium prescription"
Legal	"Meeting with divorce lawyer"
Financial	"Salary negotiation with HR"
Substance use	"AA meeting at St. Mark's Church"
Career	"Interview at Google" (optional)
Relationship	"Couples counseling" (optional)
Political	"Campaign fundraiser" (optional)
Religious	"Prayer group meeting" (optional)

CLI Reference

Core Commands

calwash login                             # Authenticate with Google
calwash clean --dry-run                   # Preview redactions
calwash clean                             # Apply redactions (backs up first)
calwash restore --dry-run                 # Preview restore from backup
calwash restore                           # Restore events from backup
calwash accounts                          # List saved accounts

Date Filtering

calwash clean --dry-run --days-back 30              # Last 30 days
calwash clean --dry-run --from-date 2025-01-01 --to-date 2025-12-31
calwash clean --dry-run --year 2024                  # All of 2024
calwash clean --dry-run --month 2025-08              # August 2025
calwash clean --dry-run --from-date today --to-date next-month

Redaction Levels

calwash clean --dry-run --redaction-level coarse    # Replace entire event content
calwash clean --dry-run --redaction-level medium     # Replace only matched patterns (default)

Multiple Accounts

calwash login --account work              # Add a second Google account
calwash clean --dry-run --account work    # Use the work account
calwash accounts                          # List all accounts

Multiple Providers

calwash login                             # Google (default)
calwash login --provider apple            # Apple iCloud (requires calwash[caldav])
calwash clean --dry-run --provider apple

Install Apple Calendar support:

pipx install calwash[caldav]

AI Detection

calwash can use a local LLM via ollama to catch sensitive content that regex patterns miss — things like "AA meeting" or "meeting with divorce lawyer" that don't contain obvious PII but are still private.

All AI processing happens locally. Your calendar data never leaves your machine.

Setup

# Interactive setup — installs ollama + downloads a model
calwash ai setup

# Or set up manually
brew install ollama        # macOS
ollama serve               # Start the server
ollama pull phi4-mini      # Download a model (2.5 GB)

Usage

calwash clean --dry-run --ai                           # Use default model
calwash clean --dry-run --ai --ai-model phi4-mini      # Choose model
calwash clean --dry-run --ai --ai-categories medical,legal,substance_use

Recommended Models

Model	Size	Notes
phi4-mini	2.5 GB	Fast, good accuracy (recommended)
llama3.2	2.0 GB	Lightweight default
llama3.1	4.7 GB	Best accuracy
gemma3n	5.6 GB	Google, efficient on-device
nemotron-mini	4.7 GB	Nvidia, strong reasoning

Any ollama-compatible model works: calwash clean --dry-run --ai --ai-model <name>

AI Management

calwash ai setup                  # Guided setup (install + model + test)
calwash ai setup --model llama3.1 # Install a specific model
calwash ai status                 # Check ollama + model readiness
calwash ai models                 # List recommended models with sizes

How It Works

1. Backup — calwash saves a full JSON backup of your events before any changes
2. Regex pass — scans event summaries, descriptions, and locations for PII patterns with validation (Luhn checksum for credit cards, format checks for SSNs, etc.)
3. AI pass (if --ai) — sends events to a local LLM to classify context-dependent sensitive content
4. Redact — replaces matched text with tags like [EMAIL REMOVED] or [SENSITIVE: MEDICAL]
5. Update — pushes cleaned events back to your calendar (or shows a dry-run preview)

Dry-Run Output

CLEANING PREVIEW
============================================================
User: [e-mail]
Total events that would be modified: 96

Event 1:
  Date: 2024-01-03T11:15:00-05:00
  Description:
    Original: Contact: [e-mail], Phone: [phone]
    Would change to: Contact: [EMAIL REMOVED], Phone: [PHONE REMOVED]

Privacy

• No cloud APIs for detection — regex runs locally, AI runs on your machine via ollama
• Google OAuth is used only to access your calendar (read + write events)
• Bundled OAuth credentials — calwash ships with a Google OAuth client ID for convenience. You can use your own by placing credentials.json at ~/.calwash/credentials.json
• Tokens stored locally at ~/.calwash/accounts/

Data Storage

~/.calwash/
  accounts/
    default/
      token.pickle          # Google OAuth token
      email.txt             # Cached email address
    work/
      token.pickle
  credentials.json          # Optional: your own OAuth client ID

Requirements

• Python 3.12+
• Google account (for Google Calendar)
• ollama (optional, for AI detection)

License

MIT