Configuration

Example .env file

Create a .env file in your project directory. PlanOpticon loads it automatically.

# =============================================================================
# PlanOpticon Configuration
# =============================================================================
# Copy this file to .env and fill in the values you need.
# You only need ONE AI provider — PlanOpticon auto-detects which are available.

# --- AI Providers (set at least one) ----------------------------------------

# OpenAI — get your key at https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-...

# Anthropic — get your key at https://console.anthropic.com/settings/keys
ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini — get your key at https://aistudio.google.com/apikey
GEMINI_API_KEY=AI...

# Azure OpenAI — from your Azure portal deployment
# AZURE_OPENAI_API_KEY=...
# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

# Together AI — https://api.together.xyz/settings/api-keys
# TOGETHER_API_KEY=...

# Fireworks AI — https://fireworks.ai/account/api-keys
# FIREWORKS_API_KEY=...

# Cerebras — https://cloud.cerebras.ai/
# CEREBRAS_API_KEY=...

# xAI (Grok) — https://console.x.ai/
# XAI_API_KEY=...

# Ollama (local, no key needed) — just run: ollama serve
# OLLAMA_HOST=http://localhost:11434

# --- Google (Drive, Docs, Sheets, Meet, YouTube) ----------------------------
# Option A: OAuth (interactive, recommended for personal use)
# Create credentials at https://console.cloud.google.com/apis/credentials
# 1. Create an OAuth 2.0 Client ID (Desktop application)
# 2. Enable these APIs: Google Drive API, Google Docs API
GOOGLE_CLIENT_ID=123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

# Option B: Service Account (automated/server-side)
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

# --- Zoom (recordings) ------------------------------------------------------
# Create an OAuth app at https://marketplace.zoom.us/develop/create
# App type: "General App" with OAuth
# Scopes: cloud_recording:read:list_user_recordings, cloud_recording:read:recording
ZOOM_CLIENT_ID=...
ZOOM_CLIENT_SECRET=...
# For Server-to-Server (no browser needed):
# ZOOM_ACCOUNT_ID=...

# --- Microsoft 365 (OneDrive, SharePoint, Teams) ----------------------------
# Register an app at https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps
# API permissions: OnlineMeetings.Read, Files.Read (delegated)
MICROSOFT_CLIENT_ID=...
MICROSOFT_CLIENT_SECRET=...

# --- Notion ------------------------------------------------------------------
# Option A: OAuth (create integration at https://www.notion.so/my-integrations)
# NOTION_CLIENT_ID=...
# NOTION_CLIENT_SECRET=...

# Option B: API key (simpler, from the same integrations page)
NOTION_API_KEY=secret_...

# --- GitHub ------------------------------------------------------------------
# Option A: Personal Access Token (simplest)
# Create at https://github.com/settings/tokens — needs 'repo' scope
GITHUB_TOKEN=ghp_...

# Option B: OAuth App (for CI/automation)
# GITHUB_CLIENT_ID=...
# GITHUB_CLIENT_SECRET=...

# --- Dropbox -----------------------------------------------------------------
# Create an app at https://www.dropbox.com/developers/apps
# DROPBOX_APP_KEY=...
# DROPBOX_APP_SECRET=...
# Or use a long-lived access token:
# DROPBOX_ACCESS_TOKEN=...

# --- General -----------------------------------------------------------------
# CACHE_DIR=~/.cache/planopticon

Environment variables reference

AI providers

Cloud services

General

Authentication

PlanOpticon uses OAuth for cloud services. Run planopticon auth once per service — tokens are saved locally and refreshed automatically.

planopticon auth google      # Google Drive, Docs, Meet, YouTube
planopticon auth dropbox     # Dropbox
planopticon auth zoom        # Zoom recordings
planopticon auth notion      # Notion pages
planopticon auth github      # GitHub repos and wikis
planopticon auth microsoft   # OneDrive, SharePoint, Teams

Credentials are stored in ~/.planopticon/. Use planopticon auth SERVICE --logout to remove them.

What each service needs

For detailed OAuth app creation walkthroughs, see the Authentication guide.

Provider routing

PlanOpticon auto-discovers available models and routes each task to the cheapest capable option:

Default models prioritize cost efficiency. For complex or high-stakes analysis, override with more capable models using --chat-model or --vision-model.

If no cloud API keys are configured, PlanOpticon automatically falls back to Ollama when a local server is running. This enables fully offline operation when paired with local Whisper for transcription.

Override with --provider, --vision-model, or --chat-model flags.

Frame sampling

Control how frames are extracted:

# Sample rate: frames per second (default: 0.5)
planopticon analyze -i video.mp4 -o ./out --sampling-rate 1.0

# Change threshold: visual difference needed to keep a frame (default: 0.15)
planopticon analyze -i video.mp4 -o ./out --change-threshold 0.1

# Periodic capture: capture a frame every N seconds regardless of change (default: 30)
# Useful for slow-evolving content like document scrolling
planopticon analyze -i video.mp4 -o ./out --periodic-capture 15

# Disable periodic capture (rely only on change detection)
planopticon analyze -i video.mp4 -o ./out --periodic-capture 0

Lower change-threshold = more frames kept. Higher sampling-rate = more candidates. Periodic capture catches content that changes too slowly for change detection (e.g., scrolling through a document during a screen share).

People/webcam frames are automatically filtered out using face detection — no configuration needed.

Focus areas

Limit processing to specific extraction types:

planopticon analyze -i video.mp4 -o ./out --focus "diagrams,action-items"

GPU acceleration

planopticon analyze -i video.mp4 -o ./out --use-gpu

Requires planopticon[gpu] extras installed.