Skip to main content

​
Hardware Requirements

​
Camera

A camera is required for Klaus to see what you’re reading.
Recommended: A USB document camera (also called a visualiser) provides a clear, stable view of the full page.
ComponentDetails
Document CameraRecommended for best experience. Example: PAKOTOO Document Camera (Amazon US) or kitchbai Visualiser (Amazon UK)
Phone on GooseneckAlternative: Phone on a ~$10-15 gooseneck mount pointed straight down at your reading surface

​
Using Your Phone as a Webcam

If you don’t have a document camera, you can use your phone:
PlatformAppDetails
macOS + iPhoneBuilt-in Continuity CameraiOS 16+, macOS Ventura+, no install needed - Learn more
macOS + AndroidCamoFree, 1080p - install on phone + Mac, pair via QR or USB
Windows + AndroidDroidCamFree - install on phone + PC, connect over Wi-Fi or USB
Windows + iPhoneCamoFree, 1080p - install on phone + PC, pair via QR or USB
Klaus auto-detects portrait orientation and rotates the image. You can override this with camera_rotation in ~/.klaus/config.toml if needed.

​
Microphone

Built-in or external microphone. Selected during the setup wizard.
Most built-in laptop microphones work fine. External microphones may provide better voice detection in noisy environments.

​
Audio Output

Built-in speakers or external speakers/headphones for TTS playback.

​
Software Requirements

​
Operating System

Klaus supports:
  • macOS (Ventura or later recommended)
  • Windows (10 or later)

​
Installation Methods

Homebrew handles all dependencies automatically. No manual installs needed.
brew tap bgigurtsis/klaus
brew install klaus

​
Dependencies

Klaus uses the following Python packages (installed automatically):
PackagePurpose
anthropic>=0.39.0Claude API client for vision + reasoning
openai>=1.58.0OpenAI API client for text-to-speech
opencv-python>=4.10.0Camera capture and image processing
sounddevice>=0.5.0Audio recording and playback
webrtcvad>=2.0.10Voice activity detection
moonshine-voice>=0.0.49Local speech-to-text
PyQt6>=6.7.0Desktop GUI framework
tavily-python>=0.5.0Web search integration
pynput>=1.7.6Global hotkey support
keyring>=25.6.0Secure API key storage (macOS only)
pyobjc-framework-AVFoundation>=10.3Native camera names (macOS only)

​
API Keys

Klaus requires API keys from three providers. The setup wizard asks for them on first launch.

​
Anthropic (Claude)

Purpose: Vision analysis and reasoning Get a key: console.anthropic.com/settings/keys Model used: claude-sonnet-4-6 (configurable in ~/.klaus/config.toml) Cost driver: This is the largest cost component. ~$0.025-0.035 per question with vision context.

​
OpenAI

Purpose: Text-to-speech (gpt-4o-mini-tts) Get a key: platform.openai.com/api-keys Cost: $0.015 per minute of generated audio

​
Tavily

Purpose: Web search (triggers automatically when Claude is uncertain) Get a key: app.tavily.com/home Free tier: 1,000 searches per month

​
API Key Storage

Keys are stored securely in Apple Keychain. Klaus resolves each key in this order:
  1. Environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY)
  2. Apple Keychain
  3. Legacy ~/.klaus/config.toml [api_keys] section (fallback)
Existing plaintext keys in config.toml are automatically migrated to Keychain on first launch.

​
Optional: Obsidian Integration

If you want Klaus to write notes directly to your Obsidian vault:
  1. Set obsidian_vault_path in ~/.klaus/config.toml (or OBSIDIAN_VAULT_PATH in .env)
  2. Or configure it in the setup wizard (“About You” step) or settings dialog (“Profile” tab)
Example: 
obsidian_vault_path = "/Users/yourname/Documents/ObsidianVault"
When configured, you can ask Klaus to take notes like:
“Save this to my daily note: The key insight from this page is…”

​
Data Storage

Klaus stores data in ~/.klaus/:
FilePurpose
config.tomlUser settings, API keys (Windows), device selections
klaus.dbSQLite database with sessions, exchanges, and knowledge profile
Images are not stored. Only a short hash of each page capture is kept for deduplication.
To reset Klaus and clear all sessions: delete ~/.klaus/klaus.db and restart the app.

​
System Permissions

​
macOS

  • Camera access: Required for page capture
  • Microphone access: Required for voice input
  • Accessibility/Input Monitoring: Optional, only needed for global hotkeys to work when Klaus is not focused
You can deny the Accessibility permission and use in-app UI buttons instead of global hotkeys.

​
Windows

No special permissions required beyond standard camera and microphone access.

Build docs developers (and LLMs) love

Get started for freeTalk to us