opencapture 0.2.0

Record keyboard/mouse activity, capture screenshots, and analyze with AI

OpenCapture

中文文档

Automatic screenshot + AI understanding tool for macOS. Records keyboard input, mouse actions, microphone audio, and uses AI to analyze everything.

Features

• Keyboard Logging - Global key listening, grouped by active window, 20-second time clustering
• Mouse Screenshots - Single click, double click, drag detection with WebP compression
• Window Tracking - Auto-detect active window, blue border annotation on screenshots
• Microphone Capture - Records when external apps use the mic; identifies the process via macOS AudioProcess API
• AI Analysis - Local Ollama or remote APIs (OpenAI, Anthropic Claude)
• Audio Transcription - Whisper-based speech-to-text for recorded audio
• Report Generation - Automated daily Markdown reports from captured data
• Privacy First - All data processed and stored locally by default

Install

Option 1: pip install (recommended)

pip install opencapture

Option 2: Clone and develop

git clone https://github.com/daibor/opencapture.git
cd opencapture
pip install -e ".[dev]"

Option 3: Download .app (macOS)

Download from GitHub Releases.

Usage

Capture Mode

# Start capture (foreground)
opencapture

# Specify storage directory
opencapture -d ~/my-captures

# Or run directly with Python (from cloned repo)
python run.py

Press Ctrl+C to stop.

Service Management (macOS)

opencapture start                      # Start as background service
opencapture stop                       # Stop service
opencapture restart                    # Restart service
opencapture status                     # Show running state and today's stats
opencapture log                        # Show recent service logs
opencapture log -f                     # Follow logs in real-time

Analysis Mode

# Analyze today's data
opencapture --analyze today

# Analyze specific date
opencapture --analyze 2026-02-01
opencapture --analyze yesterday

# Analyze single image
opencapture --image path/to/screenshot.webp

# Transcribe single audio file
opencapture --audio path/to/mic.wav

# Use remote API
export OPENAI_API_KEY=sk-xxx
opencapture --provider openai --analyze today

# Skip report generation
opencapture --analyze today --no-reports

# Check LLM service health
opencapture --health-check

# List available dates
opencapture --list-dates

# Show help
opencapture --help

System Requirements

• macOS 10.15+ (capture + analysis)
• Linux / Windows (analysis only)
• Python 3.11+
• 8GB+ RAM (for local AI analysis)
• 10GB+ disk space (for local model storage)

macOS Permissions

First run requires authorization in System Settings > Privacy & Security:

Permission	Purpose
Accessibility	Keyboard and mouse event listening
Screen Recording	Screen capture
Microphone	Audio recording (if enabled)

Data Storage

Default location: ~/opencapture/

~/opencapture/
├── 2026-02-01/
│   ├── 2026-02-01.log                              # Unified log
│   ├── click_103045_123_left_x800_y600.webp        # Click screenshot
│   ├── dblclick_103046_456_left_x800_y600.webp     # Double-click screenshot
│   ├── drag_103050_789_left_x100_y200_to_x500_y400.webp  # Drag screenshot
│   └── mic_103100_000_zoom_dur30.wav               # Mic recording
├── reports/
│   ├── 2026-02-01.md                               # Daily report
│   └── 2026-02-01_images.md                        # Image analysis
└── 2026-02-02/
    └── ...

Log Format

Keyboard input and mouse screenshots are recorded in a unified log file. Different windows are separated by triple newlines:

[2026-02-01 10:23:40] Visual Studio Code | index.ts - my-project (com.microsoft.VSCode)
[10:23:45] hello world↩
[10:23:50] ⌘s
[10:23:51] 📷 click (800,600) click_102351_123_left_x800_y600.webp


[2026-02-01 10:25:32] Terminal | zsh (com.apple.Terminal)
[10:25:35] npm run dev↩
[10:26:00] ⌃c

Key Symbols

Key	Symbol
Command	⌘
Control	⌃
Option	⌥
Shift	⇧
Enter	↩
Tab	⇥
Backspace	⌫
Escape	⎋
Arrow Keys	↑↓←→

Configuration

Edit ~/.opencapture/config.yaml to customize:

vim ~/.opencapture/config.yaml

Key settings:

Setting	Description
llm.default_provider	LLM provider (ollama / openai / anthropic)
llm.*.model	Model selection per provider
capture.output_dir	Storage directory
capture.mic_enabled	Enable microphone capture
privacy.allow_online	Allow remote API providers
prompts.*	Custom analysis prompts

Environment variables:

Variable	Purpose
OPENAI_API_KEY	Enable OpenAI provider
ANTHROPIC_API_KEY	Enable Anthropic Claude provider
OLLAMA_API_URL	Custom Ollama API endpoint
OLLAMA_MODEL	Ollama model selection
OPENCAPTURE_ALLOW_ONLINE	Allow remote providers

Uninstall

pip uninstall opencapture

To also remove captured data: rm -rf ~/opencapture To remove config: rm -rf ~/.opencapture

Privacy Warning

This tool records all keyboard input (including passwords) and screen content. Please:

• Ensure storage directory access is secured
• Regularly clean up historical data
• Use for personal purposes only
• Remote providers require explicit privacy.allow_online: true in config

License

MIT