Chowkidar

Local-first LLM model deprecation watchdog.

Chowkidar scans your project configs for LLM model strings, cross-references them against a local deprecation registry, and alerts you before models sunset — via desktop notifications and IDE rules that instruct AI assistants to update deprecated models automatically.

Everything runs on your machine. Zero data exfiltration.

Quick Start

pip install chowkidar

# First-time setup (initializes config + database)
chowkidar setup --skip-slm

# Fetch deprecation data from providers
chowkidar sync

# Scan your project
chowkidar scan .

# Check for deprecated models
chowkidar check .

Features

• Multi-format scanning: .env, YAML, TOML, JSON, Python, JavaScript, TypeScript
• Alias Unmasking: Identifies the true underlying snapshot of rolling aliases (e.g. gpt-4o) to ensure reproducibility.
• Cost Optimization (FinOps): Scans for expensive models and recommends cheaper drop-in replacements with exact percentage savings.
• Capability Guardrails: Blocks or warns about capability degradation (e.g. smaller context windows) when upgrading models.
• Privacy & Compliance: Flags consumer-free tier models that might use prompt data for training.
• Provider coverage: OpenAI, Anthropic, Google, Mistral (extensible plugin architecture)
• IDE rules (zero-config): Auto-generates rules files for Cursor, Claude Code, VS Code/Copilot, Windsurf
• MCP server: Interactive tools for querying deprecation status from your IDE
• Desktop notifications: Threshold-based alerts (90d, 30d, 7d, sunset)
• Background daemon: Periodic scanning with OS-native service installation
• Local SLM: Optional Ollama integration for parsing unstructured deprecation announcements
• Safe updates: File locking, atomic writes, automatic backups, dry-run mode
• Cross-platform: macOS, Linux, Windows

Commands

chowkidar setup [--skip-slm]     # Initialize config, DB, and optional SLM
chowkidar scan [PATH]            # Scan for model strings
chowkidar sync                   # Fetch deprecation data
chowkidar check [PATH]           # Check for deprecated models
chowkidar status                 # Show daemon status and watched projects
chowkidar watch <PATH>           # Register project for monitoring
chowkidar unwatch <PATH>         # Unregister project
chowkidar pin <MODEL> [--reason] # Suppress alerts for a model
chowkidar unpin <MODEL>          # Re-enable alerts
chowkidar snooze <MODEL> --days  # Temporarily suppress alerts
chowkidar daemon                 # Start background daemon
chowkidar install-service        # Install OS-native service
chowkidar mcp                    # Start MCP server (for IDE)
chowkidar config [KEY] [VALUE]   # View/set configuration
chowkidar update [--dry-run]     # Update deprecated models in .env
chowkidar optimize               # Find cost optimization opportunities across all models
chowkidar rules write [PATH]     # Generate IDE rules files
chowkidar rules clean [PATH]     # Remove generated rules files
chowkidar slm status             # Check SLM availability

IDE Integration

Automatic Rules (Recommended)

Chowkidar writes rules files that AI assistants auto-discover — no configuration needed:

Editor	Rules File
Cursor	.cursor/rules/chowkidar-alerts.mdc
Claude Code	.claude/rules/chowkidar-alerts.md
VS Code/Copilot	.github/copilot-instructions.md
Windsurf	.windsurfrules

Run chowkidar rules write or let the daemon do it automatically.

MCP Server (Advanced)

Add to your IDE's MCP config:

{
  "mcpServers": {
    "chowkidar": {
      "command": "chowkidar",
      "args": ["mcp"]
    }
  }
}

Configuration

Config file: ~/.chowkidar/config.toml

Key	Default	Description
auto_update	false	Allow automatic .env modifications
write_rules	true	Generate IDE rules files
gitignore_rules	true	Add rules files to .gitignore
slm_enabled	false	Use local SLM for parsing
slm_model	gemma3:1b	Ollama model for SLM
scan_interval_hours	4	How often to scan watched projects
sync_interval_hours	24	How often to fetch provider data

Security

• Zero exfiltration: No env content, API keys, or paths leave your machine
• Read-only by default: File modification requires explicit auto_update = true
• Atomic writes: All modifications use temp file + os.replace
• Automatic backups: .env.chowkidar.bak created before any change
• File locking: Prevents concurrent write corruption

License

MIT