A CLI tool for syncing Microsoft Outlook email, calendar, and tasks to local file-based formats like Maildir and vdir. Use your favorite terminal tools to manage your email and calendar.

Features

Email Synchronization: Sync emails with Microsoft Graph API to local Maildir format
Calendar Management: Two-way calendar sync with vdir/ICS support
Task Integration: Sync with Godspeed and TickTick task managers
TUI Dashboard: Interactive terminal dashboard for monitoring sync progress
Daemon Mode: Background daemon with proper Unix logging
Cross-Platform: Works on macOS, Linux, and Windows
Smart Notification Compression: Automatically detects and compresses transactional notification emails (GitLab, GitHub, Jira, Confluence, Datadog, Renovate) into terminal-friendly summaries

Quick Start

Prerequisites

Python 3.12 or higher
uv package manager (recommended)

Installation

# Clone the repository
git clone https://github.com/timothybendt/luk.git
cd luk

# Run the installation script
./install.sh

Manual Installation

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Setup configuration directories
mkdir -p ~/.config/luk
mkdir -p ~/.local/share/luk

Configuration

Create a configuration file at ~/.config/luk/config.env:

Notification Email Compression

LUK includes intelligent notification email compression to reduce visual noise from automated emails (GitLab, GitHub, Jira, Confluence, Datadog, Renovate). Configure it in ~/.config/luk/mail.toml:

[content_display]
# Enable/disable notification compression
compress_notifications = true

# Compression mode:
# - "summary": Brief one-page view (default)
# - "detailed": More details in structured format
# - "off": Disable compression, show full emails
notification_compression_mode = "summary"

Features:

Automatic detection: Identifies notification emails by sender domain and subject patterns
Type-specific summaries: Extracts relevant info per platform (pipeline IDs, PR numbers, etc.)
Terminal-friendly formatting: Clean markdown with icons and clear hierarchy
Toggle support: Press m in mail view to switch between compressed and full email

Demo:

python demo_notification_compression.py

See mail.toml.example for full configuration options.

General Configuration

# Microsoft Graph settings
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_TENANT_ID=your_tenant_id

# Email settings
MAILDIR_PATH=~/Mail
NOTES_DIR=~/Documents/Notes

# Godspeed settings
GODSPEED_EMAIL=your_email@example.com
GODSPEED_PASSWORD=your_password
GODSPEED_TOKEN=your_token
GODSPEED_SYNC_DIR=~/Documents/Godspeed

# TickTick settings
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret

Usage

Basic Commands

# Show help
luk --help

# Run sync with default settings
luk sync run

# Run with TUI dashboard
luk sync run --dashboard

# Start daemon mode
luk sync run --daemon

# Stop daemon
luk sync stop

# Check daemon status
luk sync status

Sync Options

# Dry run (no changes)
luk sync run --dry-run

# Specify organization
luk sync run --org mycompany

# Enable notifications
luk sync run --notify

# Download attachments
luk sync run --download-attachments

# Two-way calendar sync
luk sync run --two-way-calendar

# Custom calendar directory
luk sync run --vdir ~/Calendars

Dashboard Mode

The TUI dashboard provides real-time monitoring of sync operations:

Status Display: Current sync status and metrics
Progress Bars: Visual progress for each sync component
Activity Log: Scrollable log of all sync activities
Keyboard Shortcuts:
- q: Quit dashboard
- l: Toggle log visibility
- r: Refresh status

Daemon Mode

Run luk as a background daemon with proper Unix logging:

# Start daemon
luk sync run --daemon

# Check status
luk sync status

# View logs
cat ~/.local/share/luk/luk.log

# Stop daemon
luk sync stop

Daemon logs are stored at ~/.local/share/luk/luk.log with automatic rotation.

Architecture

Core Components

Sync Engine: Handles email, calendar, and task synchronization
TUI Dashboard: Interactive monitoring interface using Textual
Daemon Service: Background service with logging and process management
Configuration: Environment-based configuration system

Directory Structure

src/
├── cli/                    # CLI commands and interfaces
│   ├── sync.py            # Main sync command
│   ├── sync_dashboard.py  # TUI dashboard
│   ├── sync_daemon.py     # Daemon service
│   └── ...
├── services/              # External service integrations
│   ├── microsoft_graph/   # Microsoft Graph API
│   ├── godspeed/         # Godspeed task manager
│   ├── ticktick/         # TickTick API
│   └── ...
└── utils/                 # Utility functions

Development

Setup Development Environment

# Clone repository
git clone https://github.com/timothybendt/luk.git
cd luk

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run ruff format .

# Type checking
uv run mypy src/

Project Structure

pyproject.toml: Project configuration and dependencies
src/cli/: CLI commands and user interfaces
src/services/: External service integrations
src/utils/: Shared utilities and helpers
tests/: Test suite

Building for Distribution

# Build package
uv run build

# Check package
uv run twine check dist/*

# Upload to PyPI (for maintainers)
uv run twine upload dist/*

Troubleshooting

Common Issues

Authentication Errors: Ensure Microsoft Graph credentials are properly configured
Permission Denied: Check file permissions for Maildir and calendar directories
Daemon Not Starting: Verify log directory exists and is writable
TUI Not Rendering: Ensure terminal supports Textual requirements

Debug Mode

Enable debug logging:

export LOG_LEVEL=DEBUG
luk sync run --dry-run

Log Files

Daemon Logs: ~/.local/share/luk/luk.log
Sync State: ~/.local/share/luk/sync_state.json
Configuration: ~/.config/luk/

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
Submit a pull request

Code Style

This project uses:

Ruff for linting and formatting
MyPy for type checking
Black for code formatting
Pre-commit hooks for quality control

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: GitHub Wiki
Discussions: GitHub Discussions

Changelog

v0.1.0

Initial release
Email synchronization with Microsoft Graph
Calendar sync with vdir/ICS support
Godspeed and TickTick integration
TUI dashboard
Daemon mode with logging
Cross-platform support