Metadata-Version: 2.4
Name: chowkidar
Version: 0.6.0
Summary: Local-first LLM model deprecation watchdog — scans your configs, alerts on sunsets, and instructs your IDE to update.
Author: Bhavishya
License: MIT
Keywords: ai,deprecation,llm,mcp,model,watchdog
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: filelock>=3.12.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: plyer>=2.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: schedule>=1.2.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: slm
Requires-Dist: ollama>=0.4.0; extra == 'slm'
Description-Content-Type: text/markdown

# Chowkidar

[![PyPI Version](https://img.shields.io/pypi/v/chowkidar.svg)](https://pypi.org/project/chowkidar/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/chowkidar.svg)](https://pypi.org/project/chowkidar/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Chowkidar** is a secure, local-first LLM model deprecation watchdog. It scans your codebase and configuration files for LLM model references, cross-references them with a locally cached deprecation database, and alerts you before models sunset—safely guiding updates before production breakage.

Everything runs on your machine. Zero data exfiltration.

---

## Core Features

- **Multi-Format Scanner & Structured Writers**: Scans and parses model strings in `.env`, JSON, YAML, TOML, `docker-compose`, and source code. At the 1-day threshold, safely auto-updates structured configuration files (with atomic writes, backups, and file locking).
- **Notification-First Governance & Per-Reference Audit Log**: Alerts via native OS toasts and webhooks (Slack/Discord/generic). Every notification and update attempt is logged in a detailed audit ledger.
- **Deployment Signal Detector**: Analyzes repo evidence (CI, Docker, Kubernetes, Vercel, Terraform) to flag likely deployed environments, preventing blind or risky local writes.
- **Cloud Environment Adapters**: Explicit, credential-backed adapters for dry-running, updating, and verifying remote secret/config stores on Vercel, Kubernetes, AWS Secrets/SSM, GCP Secret Manager, and Azure Key Vault.
- **Unified Risk & Capability Analysis**: Guarantees migrations won't degrade your system by verifying context windows, output tokens, vision, tool usage, JSON mode, streaming, and cost impacts.
- **AI-Assistant Rules & MCP Server**: Generates zero-config rule instructions (`.mdc`, `CLAUDE.md`, etc.) to guide Cursor, Claude Code, Copilot, and Windsurf, alongside an interactive MCP server.

---

## Installation & Setup

```bash
# Install globally via pipx (recommended) or pip
pipx install chowkidar

# Initialize configuration and local sqlite registry
chowkidar setup --skip-slm

# Fetch deprecation updates from providers (OpenAI, Anthropic, Google, Mistral)
chowkidar sync

# Verify native notifications and setup clickable HTML reports
chowkidar test-notify
```

---

## Command Reference

| Command | Description |
|---|---|
| `chowkidar setup` | Initialize config (`~/.chowkidar/config.toml`), registry DB, and SLM |
| `chowkidar sync` | Scrape latest model deprecation and sunset schedules from providers |
| `chowkidar scan [PATH]` | Find and extract all LLM model references across your codebase |
| `chowkidar check [PATH]` | Check found references against the local deprecation database |
| `chowkidar status` | Show watched projects, sync freshness, and daemon health |
| `chowkidar watch <PATH>` | Register a directory path for periodic background scans |
| `chowkidar unwatch <PATH>` | Unregister a directory from background monitoring |
| `chowkidar pin <MODEL>` | Suppress notifications for a specific model ID (keeps existing value) |
| `chowkidar unpin <MODEL>` | Re-enable notifications for a previously pinned model |
| `chowkidar snooze <MODEL> --days N` | Temporarily silence deprecation warnings for a model |
| `chowkidar daemon` | Start the periodic background monitoring loop (runs every 4 hours) |
| `chowkidar install-service` | Install and register the daemon as an OS-native background service |
| `chowkidar uninstall-service` | Remove the OS-native background daemon service |
| `chowkidar logs` | Stream or tail daemon execution logs |
| `chowkidar mcp` | Start stdio MCP server for rich Cursor, Claude Code, and Copilot queries |
| `chowkidar config` | Read or set configuration variables (`auto_update`, `webhook_url`, etc.) |
| `chowkidar update` | Interactively review and apply recommended model updates to structured configs |
| `chowkidar gate` | CI-friendly checker; exits with a non-zero code if critical sunsets are found |
| `chowkidar cost` | View pricing comparisons and FinOps savings between models |
| `chowkidar diff <OLD> <NEW>` | Perform direct comparison of context size, pricing, and features |
| `chowkidar optimize` | Search scanned files for cheaper recommended drop-in model replacements |
| `chowkidar report` | Generate comprehensive Markdown, JSON, or interactive HTML reports |
| `chowkidar predict` | Estimate model sunset probability based on historical release patterns |
| `chowkidar dashboard` | Open a lightweight terminal TUI to visualize model states across projects |
| `chowkidar test-migration` | Mock prompt completion outputs on old vs new models before migrating |
| `chowkidar test-notify` | Fire a mock native desktop alert and test report click-through action |
| `chowkidar rules write` | Generate local prompt files (.mdc, CLAUDE.md) instructing AI agents |
| `chowkidar rules clean` | Safely wipe Chowkidar-generated rule instructions from the project |
| `chowkidar slm status` | Inspect Ollama connection status and system hardware profile |
| `chowkidar slm choose` | Analyze CPU/RAM and configure/pull the best small local model (SLM) |
| `chowkidar slm unload` | Unload the SLM from memory to instantly reclaim system RAM |
| `chowkidar hook install` | Register a lightweight terminal cd warning hook |
| `chowkidar hook uninstall` | Uninstall the terminal cd warning hook |

---

## Editor Integration

### Passive AI Rules (Zero-Config)
AI editors auto-discover instructions in your project workspace. Chowkidar outputs non-destructive rule tables wrapped in `<!-- chowkidar -->` comments:
* **Cursor**: `.cursor/rules/chowkidar-alerts.mdc`
* **Claude Code**: `.claude/rules/chowkidar-alerts.md`
* **VS Code / Copilot**: `.github/copilot-instructions.md`
* **Windsurf**: `.windsurfrules`

### MCP Server (Active)
Configure the stdio MCP server in your IDE's configuration file:
```json
{
  "mcpServers": {
    "chowkidar": {
      "command": "chowkidar",
      "args": ["mcp"]
    }
  }
}
```

---

## Security & Local Safety

- **Privacy First**: No code, project paths, keys, or configurations are ever sent to external APIs.
- **Safe Writes**: Modifying configuration files requires setting `auto_update = true` in your config. Every update atomic-writes via a temp file and saves a `.chowkidar.bak` file for automatic rollback.
- **Concurrent-Safe**: Uses system-level `filelock` to protect files from concurrent daemon/CLI writes.

## License

MIT
