@mcptoolshop/claude-guardian 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-02-27
+
+### Added
+- Stale session cleanup: `preflight --fix` and `guardian_preflight_fix` now detect and remove
+  old UUID-named session transcripts (.jsonl, .jsonl.gz) and session directories
+- Configurable retention: sessions older than 3 days are cleaned (1.5 days in aggressive mode)
+- Protected entries: `memory/` and `sessions-index.json` are never touched
+- Scan-time warning: `preflight` reports stale session count and size before fix
+- 6 new tests for session cleanup
+
+## [1.0.0] - 2026-02-27
+
+First public release.
+
+### Added
+- `preflight` command — scan and fix Claude log bloat (rotate, gzip, trim)
+- `doctor` command — diagnostics bundle (zip) with system info, log tails, journal
+- `run` command — watchdog with hang/crash detection, optional auto-restart
+- `watch` daemon — continuous 2-second polling, incident tracking, budget enforcement
+- `status` command with `--banner` flag for one-line health summaries
+- `budget` CLI command (show/acquire/release) for concurrency management
+- Composite hang detection (log mtime + CPU activity + grace window)
+- Incident state machine (ok → warn → critical lifecycle)
+- Bundle deduplication (one per incident)
+- Concurrency budget system (cap transitions: ok=4, warn=2, critical=1)
+- Lease-based concurrency control with TTL auto-expiry and 60s hysteresis
+- Handle count signal (Windows/Linux/macOS)
+- Attention channel: synthesized top-level signal (none/info/warn/critical)
+- 8 MCP tools: `guardian_status`, `guardian_preflight_fix`, `guardian_doctor`, `guardian_nudge`, `guardian_budget_get`, `guardian_budget_acquire`, `guardian_budget_release`, `guardian_recovery_plan`
+- `GuardianError` structured error type with code, hint, and cause
+- MCP tools return structured errors (code + hint), never stack traces
+- State/budget file corruption recovery: auto-backup + graceful reset
+- CLI `--debug` flag for full stack traces
+- Consistent CLI exit codes: 0 ok, 1 user error, 2 runtime error
+- `npm run verify` script (test + build + pack)
+- SECURITY.md, HANDBOOK.md, SHIP_GATE.md
+- Landing page via @mcptoolshop/site-theme
+- README translations: ja, zh, es, fr, hi, it, pt-BR

package/HANDBOOK.md

@@ -0,0 +1,209 @@
+# Claude Guardian Handbook
+
+Field manual for operating Claude Guardian. Covers daily use, incident response, budget management, and diagnostics.
+
+## Daily operations
+
+### Start of session
+
+```bash
+claude-guardian status
+```
+
+If `risk=ok` and disk is healthy, you're good. If the daemon isn't running:
+
+```bash
+claude-guardian watch --verbose &
+```
+
+The daemon polls every 2 seconds, tracks hang risk, manages the concurrency budget, and persists state for the MCP server.
+
+### Embed in prompts
+
+Add the guardian to your Claude Code MCP config (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "guardian": {
+      "command": "npx",
+      "args": ["claude-guardian", "mcp"]
+    }
+  }
+}
+```
+
+Claude can then call `guardian_status` at any time to check health.
+
+### One-line banner
+
+```bash
+claude-guardian status --banner
+```
+
+Output: `[guardian] disk=607GB | logs=150MB | procs=2 | cpu=12% | rss=800MB | quiet=0s | risk=ok`
+
+Useful for embedding in shell prompts or session start hooks.
+
+---
+
+## Attention levels
+
+Guardian synthesizes all signals into a single attention level. Check it with `guardian_status` (CLI or MCP).
+
+### `attn=NONE` — All clear
+
+No action needed. The daemon is monitoring in the background.
+
+### `attn=INFO` — Awareness
+
+Something is noteworthy but not urgent. Examples:
+- Budget cap is reduced (recovering from a previous warn/critical)
+- An incident just closed but is still tracked
+
+**What to do:** Nothing immediate. Continue working normally.
+
+### `attn=WARN` — Elevated risk
+
+Hang risk is elevated, or disk is low. Guardian has detected inactivity or resource pressure.
+
+**What to do:**
+1. Call `guardian_nudge` — it will auto-fix what it can (rotate logs, capture bundles)
+2. Check `guardian_budget_get` — cap is likely reduced to 2
+3. Reduce concurrency: fewer parallel tasks, smaller batches
+4. Monitor with `guardian_status` every few minutes
+
+### `attn=CRITICAL` — Immediate action needed
+
+Hang risk is critical. Claude Code may be stuck. No activity for 600+ seconds with low CPU.
+
+**What to do:**
+1. Call `guardian_nudge` — captures a diagnostics bundle if one hasn't been taken
+2. Call `guardian_recovery_plan` — get exact step-by-step instructions
+3. Budget cap is reduced to 1 — stop starting new heavy work
+4. If no recovery in 2 minutes, restart Claude Code manually
+5. After restart, the budget will recover to cap=4 after 60 seconds of sustained `risk=ok`
+
+---
+
+## Budget and leases
+
+The budget system prevents multiple agents or tasks from dogpiling Claude when it's already stressed.
+
+### How it works
+
+- **Base cap:** 4 concurrent slots
+- **Warn cap:** 2 slots (when `risk=warn`)
+- **Critical cap:** 1 slot (when `risk=critical`)
+- **Hysteresis:** After risk returns to `ok`, the cap stays reduced for 60 seconds before restoring to base
+
+### Acquire before heavy work
+
+```bash
+claude-guardian budget acquire 1 --ttl 120 --reason "batch-processing"
+```
+
+Or via MCP:
+```
+guardian_budget_acquire { slots: 1, ttlSeconds: 120, reason: "batch-processing" }
+```
+
+If granted, you get a lease ID. If denied, the cap is full — wait or reduce load.
+
+### Release when done
+
+```bash
+claude-guardian budget release <lease-id>
+```
+
+Or via MCP:
+```
+guardian_budget_release { leaseId: "<id>" }
+```
+
+Leases auto-expire after their TTL, but releasing early frees slots for others immediately.
+
+### Check budget state
+
+```bash
+claude-guardian budget show
+```
+
+Shows current cap, slots in use, active leases with TTL countdown.
+
+### The contract
+
+The budget is **advisory**. Guardian doesn't block or kill anything. The contract is:
+1. Check `guardian_budget_get` before starting heavy work
+2. If `slotsAvailable > 0`, call `guardian_budget_acquire`
+3. If denied, back off — the system is under pressure
+4. Always release when done
+
+Tools and agents that respect this contract prevent cascading failures.
+
+---
+
+## Doctor bundles
+
+When something goes wrong, Guardian captures evidence — not guesses.
+
+### Generate a bundle
+
+```bash
+claude-guardian doctor --out ./my-bundle.zip
+```
+
+Or via MCP: `guardian_doctor`
+
+### What's in the bundle
+
+| File | Contents |
+|------|----------|
+| `summary.json` | System info, disk, memory, CPU, preflight results |
+| `process.json` | Snapshot of all Claude processes (PID, CPU, memory, handles, uptime) |
+| `timeline.json` | Chronological events (journal entries, incidents, state changes) |
+| `log-tails/*.txt` | Last 500 lines of each Claude log file |
+| `journal.jsonl` | Full guardian action journal |
+| `events.jsonl` | Incident log |
+| `state.json` | Guardian state at time of capture |
+
+### Attach to issues
+
+When filing a bug report:
+1. Run `claude-guardian doctor`
+2. Note the bundle path in the output
+3. Attach the `.zip` to your GitHub issue
+4. The bundle contains no API keys, tokens, or user content — only system metrics, log tails, and guardian's own journal
+
+### Automatic capture
+
+The daemon captures bundles automatically when:
+- Risk escalates to `warn` or `critical` (one bundle per incident, deduplicated)
+- The watchdog (`claude-guardian run`) detects a hang or crash
+
+Bundle paths are stored in the incident record and shown in `guardian_status`.
+
+---
+
+## Corruption recovery
+
+Guardian handles its own file corruption gracefully:
+
+- **state.json corrupt:** Backed up to `state.json.corrupt.<timestamp>`, state resets to empty. The daemon rebuilds on next poll.
+- **budget.json corrupt:** Backed up to `budget.json.corrupt.<timestamp>`, budget resets to defaults (cap=4, no leases).
+
+If you see `[guardian] WARNING: state.json is corrupt` in your console, the backup is in `~/.claude-guardian/`. The guardian continues operating normally after reset.
+
+---
+
+## Quick reference
+
+| Situation | Command |
+|-----------|---------|
+| Start of session | `claude-guardian status` |
+| Background monitoring | `claude-guardian watch` |
+| Fix log bloat | `claude-guardian preflight --fix` |
+| Something is wrong | `claude-guardian doctor` |
+| Check budget | `claude-guardian budget show` |
+| MCP: safe auto-fix | `guardian_nudge` |
+| MCP: what do I do? | `guardian_recovery_plan` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-guardian/readme.png" width="400" alt="claude-guardian" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/claude-guardian/actions"><img src="https://github.com/mcp-tool-shop-org/claude-guardian/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-guardian/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page" /></a>
+</p>
+
+Computadora de vuelo para Claude Code: rotación de registros, supervisión, paquetes de fallos y autoconciencia del MCP.
+
+Claude Guardian es una capa de confiabilidad local que mantiene las sesiones de Claude Code en buen estado. Detecta el crecimiento excesivo de los registros, la presión en el disco y las interrupciones antes de que causen problemas, captura evidencia cuando algo sale mal y expone un servidor MCP para que Claude pueda realizar un automonitoreo durante la sesión.
+
+## ¿Qué hace?
+
+| Comando | Propósito |
+|---------|---------|
+| `preflight` | Escanea los registros del proyecto Claude, informa sobre directorios/archivos de gran tamaño, opcionalmente corrige automáticamente. |
+| `doctor` | Genera un paquete de diagnóstico (zip) con información del sistema, fragmentos de registros y un registro. |
+| `run -- <cmd>` | Ejecuta cualquier comando con supervisión, crea automáticamente un paquete en caso de fallo/interrupción. |
+| `status` | Comprobación de estado: espacio libre en disco, tamaños de los registros, advertencias. |
+| `watch` | Demonio en segundo plano: monitoreo continuo, seguimiento de incidentes, cumplimiento del presupuesto. |
+| `budget` | Visualiza y gestiona el presupuesto de concurrencia (mostrar/obtener/liberar). |
+| `mcp` | Inicia el servidor MCP (8 herramientas) para el automonitoreo de Claude Code. |
+
+## Instalación
+
+```bash
+npm install -g claude-guardian
+```
+
+O ejecútelo directamente:
+
+```bash
+npx claude-guardian preflight
+```
+
+## Comienzo rápido
+
+### Verifique su entorno
+
+```bash
+claude-guardian status
+```
+
+```
+=== Claude Guardian Preflight ===
+
+Disk free: 607.13GB [OK]
+Claude projects: C:\Users\you\.claude\projects
+Total size: 1057.14MB
+
+Project directories (by size):
+  my-project: 1020.41MB
+
+Issues found:
+  [WARNING] Project log dir is 1020.41MB (limit: 200MB)
+  [WARNING] File is 33.85MB (limit: 25MB)
+
+[guardian] disk=607.13GB | logs=1057.14MB | issues=2
+```
+
+### Corrige automáticamente el crecimiento excesivo de los registros
+
+```bash
+claude-guardian preflight --fix
+```
+
+Rota los registros antiguos (gzip), recorta los archivos `.jsonl` y `.log` de gran tamaño a sus últimas N líneas. Cada acción se registra en un archivo de registro para facilitar el seguimiento.
+
+### Genera un informe de fallo
+
+```bash
+claude-guardian doctor --out ./bundle.zip
+```
+
+Crea un archivo zip que contiene:
+- `summary.json` — información del sistema, informe de tamaño de archivo, resultados de la verificación inicial.
+- `log-tails/` — las últimas 500 líneas de cada archivo de registro.
+- `journal.jsonl` — cada acción que ha realizado el guardián.
+
+### Ejecute con supervisión
+
+```bash
+claude-guardian run -- claude
+claude-guardian run --auto-restart --hang-timeout 120 -- node server.js
+```
+
+El sistema de supervisión:
+1. Ejecuta su comando como un proceso secundario.
+2. Supervisa la salida estándar/error estándar para detectar actividad.
+3. Si no hay actividad durante `--hang-timeout` segundos, captura un paquete de diagnóstico.
+4. Si el proceso falla, captura un paquete y, opcionalmente, se reinicia con un intervalo de reintento.
+
+## Servidor MCP (la verdadera clave)
+
+Registre el guardián como un servidor MCP local para que Claude pueda realizar un automonitoreo:
+
+Agregue lo siguiente a `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "guardian": {
+      "command": "npx",
+      "args": ["claude-guardian", "mcp"]
+    }
+  }
+}
+```
+
+Luego, Claude puede llamar a:
+
+| Herramienta | Lo que devuelve |
+|------|----------------|
+| `guardian_status` | Disco, registros, procesos, riesgo de interrupción, presupuesto, nivel de atención. |
+| `guardian_preflight_fix` | Ejecuta la rotación/recorte de registros y devuelve un informe de antes y después. |
+| `guardian_doctor` | Crea un paquete de diagnóstico (zip) y devuelve la ruta y un resumen. |
+| `guardian_nudge` | Corrección automática segura: corrige los registros si están hinchados, captura un paquete si es necesario. |
+| `guardian_budget_get` | Límite de concurrencia actual, espacios utilizados, concesiones activas. |
+| `guardian_budget_acquire` | Solicita espacios de concurrencia (devuelve el ID de la concesión). |
+| `guardian_budget_release` | Libera una concesión cuando hayas terminado con el trabajo intensivo. |
+| `guardian_recovery_plan` | Plan de recuperación paso a paso que indica las herramientas exactas a utilizar. |
+
+Esto permite que Claude diga: "La atención es de NIVEL DE ADVERTENCIA. Ejecutando `guardian_nudge`, luego reduciendo la concurrencia".
+
+## Configuración
+
+Tres opciones de configuración (todo lo demás está codificado con valores predeterminados razonables):
+
+| Bandera | Valor predeterminado | Descripción |
+|------|---------|-------------|
+| `--max-log-mb` | `200` | Tamaño máximo del directorio de registros del proyecto en MB. |
+| `--hang-timeout` | `300` | Segundos de inactividad antes de declarar una interrupción. |
+| `--auto-restart` | `false` | Reiniciar automáticamente en caso de fallo/interrupción. |
+
+Además, existe una restricción codificada:
+- **Espacio libre en disco < 5 GB** → el modo agresivo se habilita automáticamente (menor retención, umbrales más bajos).
+
+## Modelo de confianza
+
+Claude Guardian es **solo local**. No tiene ningún listener de red, ni telemetría ni dependencia de la nube.
+
+**Lo que lee:** `~/.claude/projects/` (archivos de registro, tamaños, tiempos de modificación), lista de procesos (CPU, memoria, tiempo de actividad, recuentos de identificadores para los procesos relacionados con Claude a través de `pidusage`).
+
+**Lo que escribe:** `~/.claude-guardian/` (state.json, budget.json, journal.jsonl, paquetes de diagnóstico). Todos los archivos están ubicados en el directorio de inicio del usuario.
+
+**¿Qué información recopila en los paquetes?** Información del sistema (sistema operativo, CPU, memoria, disco), fragmentos de archivos de registro (las últimas 500 líneas), instantáneas de procesos y el propio registro de Guardian. No recopila claves de API, tokens, credenciales ni contenido de usuario.
+
+**Acciones peligrosas: lo que Guardian NO hará:**
+- Matar procesos o enviar señales (no `SIGKILL`, no `SIGTERM`)
+- Reiniciar Claude Code o cualquier otro proceso
+- Eliminar archivos (la rotación es mediante compresión gzip, el recorte consiste en mantener las últimas N líneas)
+- Realizar solicitudes de red o enviar información a un servidor central
+- Aumentar privilegios o acceder a los datos de otros usuarios.
+
+Si alguna vez se añadiera la función de matar procesos o el reinicio automático, estará habilitada mediante una opción explícita, documentada aquí, y estará desactivada de forma predeterminada.
+
+## Principios de diseño
+
+- **Evidencia sobre suposiciones** — cada acción genera una entrada en el registro; los paquetes de registro capturan el estado, no conjeturas.
+- **Determinista** — no utiliza aprendizaje automático ni heurísticas más allá de la edad y el tamaño de los archivos. Tabla de decisiones que se puede leer en 60 segundos.
+- **Seguro por defecto** — la rotación es mediante compresión gzip (reversible), el recorte consiste en mantener las últimas N líneas (los datos se conservan), no hay eliminaciones en la versión 1.
+- **Dependencias básicas** — commander, pidusage, archiver, @modelcontextprotocol/sdk. Eso es todo.
+
+## Desarrollo
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Licencia
+
+MIT
+
+---
+
+Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>

package/README.fr.md

@@ -0,0 +1,185 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.md">English</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-guardian/readme.png" width="400" alt="claude-guardian" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/claude-guardian/actions"><img src="https://github.com/mcp-tool-shop-org/claude-guardian/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" /></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-guardian/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page" /></a>
+</p>
+
+Ordinateur de bord pour Claude Code : rotation des journaux, surveillance, regroupement des erreurs, et auto-évaluation de l'environnement d'exécution (MCP).
+
+Claude Guardian est une couche de fiabilité locale qui maintient les sessions Claude Code en bon état. Il détecte les problèmes de taille des journaux, la saturation du disque et les blocages avant qu'ils ne causent des problèmes, enregistre les informations pertinentes en cas de problème, et expose un serveur MCP afin que Claude puisse s'auto-surveiller pendant les sessions.
+
+## Ce qu'il fait
+
+| Commande | Fonction |
+|---------|---------|
+| `preflight` | Analyse les journaux du projet Claude, signale les répertoires/fichiers trop volumineux, corrige automatiquement (optionnel). |
+| `doctor` | Génère un ensemble de diagnostics (zip) contenant des informations système, les dernières lignes des journaux et un journal. |
+| `run -- <cmd>` | Exécute n'importe quelle commande avec surveillance, crée automatiquement un regroupement en cas de plantage/blocage. |
+| `status` | Vérification de l'état : espace disque disponible, taille des journaux, avertissements. |
+| `watch` | Démon en arrière-plan : surveillance continue, suivi des incidents, application des limites. |
+| `budget` | Affiche et gère la limite de concurrence (afficher/acquérir/libérer). |
+| `mcp` | Démarre le serveur MCP (8 outils) pour l'auto-surveillance de Claude Code. |
+
+## Installation
+
+```bash
+npm install -g claude-guardian
+```
+
+Ou exécutez directement :
+
+```bash
+npx claude-guardian preflight
+```
+
+## Démarrage rapide
+
+### Vérifiez votre environnement
+
+```bash
+claude-guardian status
+```
+
+```
+=== Claude Guardian Preflight ===
+
+Disk free: 607.13GB [OK]
+Claude projects: C:\Users\you\.claude\projects
+Total size: 1057.14MB
+
+Project directories (by size):
+  my-project: 1020.41MB
+
+Issues found:
+  [WARNING] Project log dir is 1020.41MB (limit: 200MB)
+  [WARNING] File is 33.85MB (limit: 25MB)
+
+[guardian] disk=607.13GB | logs=1057.14MB | issues=2
+```
+
+### Corrige automatiquement les problèmes de taille des journaux
+
+```bash
+claude-guardian preflight --fix
+```
+
+Effectue la rotation des anciens journaux (gzip), réduit la taille des fichiers `.jsonl` et `.log` trop volumineux en ne conservant que les N dernières lignes. Chaque action est enregistrée dans un fichier journal pour la traçabilité.
+
+### Génère un rapport de plantage
+
+```bash
+claude-guardian doctor --out ./bundle.zip
+```
+
+Crée un fichier zip contenant :
+- `summary.json` : informations système, rapport de taille des fichiers, résultats de vérification préliminaire.
+- `log-tails/` : les 500 dernières lignes de chaque fichier journal.
+- `journal.jsonl` : toutes les actions effectuées par le système de surveillance.
+
+### Exécute avec surveillance
+
+```bash
+claude-guardian run -- claude
+claude-guardian run --auto-restart --hang-timeout 120 -- node server.js
+```
+
+La surveillance :
+1. Lance votre commande en tant que processus enfant.
+2. Surveille la sortie standard (stdout) et la sortie d'erreur (stderr) pour détecter l'activité.
+3. Si aucune activité pendant `--hang-timeout` secondes, un ensemble de diagnostics est créé.
+4. Si le processus plante, un ensemble est créé, et il peut être redémarré avec un délai progressif.
+
+## Serveur MCP (la véritable fonctionnalité)
+
+Enregistrez le système de surveillance en tant que serveur MCP local afin que Claude puisse s'auto-surveiller :
+
+Ajoutez ceci à `~/.claude.json` :
+
+```json
+{
+  "mcpServers": {
+    "guardian": {
+      "command": "npx",
+      "args": ["claude-guardian", "mcp"]
+    }
+  }
+}
+```
+
+Ensuite, Claude peut appeler :
+
+| Outil | Ce qu'il renvoie |
+|------|----------------|
+| `guardian_status` | Espace disque, journaux, processus, risque de blocage, limite, niveau d'attention. |
+| `guardian_preflight_fix` | Effectue la rotation/réduction des journaux, renvoie un rapport avant/après. |
+| `guardian_doctor` | Crée un ensemble de diagnostics (zip), renvoie le chemin et un résumé. |
+| `guardian_nudge` | Correction automatique sécurisée : corrige les journaux s'ils sont trop volumineux, crée un ensemble si nécessaire. |
+| `guardian_budget_get` | Limite de concurrence actuelle, emplacements utilisés, licences actives. |
+| `guardian_budget_acquire` | Demande des emplacements de concurrence (renvoie l'ID de la licence). |
+| `guardian_budget_release` | Libère une licence une fois le travail intensif terminé. |
+| `guardian_recovery_plan` | Plan de récupération étape par étape, indiquant les outils à utiliser. |
+
+Cela permet à Claude de dire : "L'attention est à niveau AVERTISSEMENT. Exécution de `guardian_nudge`, puis réduction de la concurrence."
+
+## Configuration
+
+Trois paramètres (tout le reste est codé en dur avec des valeurs par défaut raisonnables) :
+
+| Paramètre | Valeur par défaut | Description |
+|------|---------|-------------|
+| `--max-log-mb` | `200` | Taille maximale du répertoire des journaux du projet en Mo. |
+| `--hang-timeout` | `300` | Nombre de secondes d'inactivité avant de déclarer un blocage. |
+| `--auto-restart` | `false` | Redémarrage automatique en cas de plantage/blocage. |
+
+Plus une règle de sécurité codée en dur :
+- **Espace disque disponible < 5 Go** → le mode agressif est activé automatiquement (conservation plus courte, seuils plus bas).
+
+## Modèle de confiance
+
+Claude Guardian est **local uniquement**. Il n'a pas de listener réseau, de télémétrie ni de dépendance au cloud.
+
+**Ce qu'il lit :** `~/.claude/projects/` (fichiers journaux, tailles, dates de modification), liste des processus (utilisation du CPU, mémoire, temps de fonctionnement, nombre de descripteurs pour les processus liés à Claude via `pidusage`).
+
+**Ce qu'il écrit :** `~/.claude-guardian/` (state.json, budget.json, journal.jsonl, doctor bundles). Tous les fichiers se trouvent dans le répertoire personnel de l'utilisateur.
+
+**Ce qu'il collecte dans les rapports :** Informations système (OS, CPU, mémoire, disque), extraits de fichiers journaux (les 500 dernières lignes), instantanés des processus et le propre journal de Guardian. Aucune clé API, aucun jeton, aucune identifiant, ni aucun contenu utilisateur.
+
+**Actions dangereuses — ce que Guardian NE fera PAS :**
+- Terminer des processus ou envoyer des signaux (pas de `SIGKILL`, pas de `SIGTERM`)
+- Redémarrer Claude Code ou tout autre processus
+- Supprimer des fichiers (la rotation se fait par compression gzip, la suppression se limite aux N dernières lignes)
+- Effectuer des requêtes réseau ou contacter un serveur central
+- Accorder des privilèges supérieurs ou accéder aux données d'autres utilisateurs
+
+Si la terminaison de processus ou le redémarrage automatique étaient un jour ajoutés, cela se ferait via un indicateur d'activation explicite, documenté ici, et serait désactivé par défaut.
+
+## Principes de conception
+
+- **Preuves plutôt que suppositions** — chaque action génère une entrée de journal ; les rapports capturent l'état, et non des conjectures.
+- **Déterministe** — pas d'apprentissage automatique, pas d'heuristiques au-delà de l'âge et de la taille des fichiers. Tableau de décision que vous pouvez lire en 60 secondes.
+- **Sûr par défaut** — la rotation se fait par compression gzip (réversible), la suppression se limite aux N dernières lignes (les données sont préservées), aucune suppression dans la version 1.
+- **Dépendances simples** — commander, pidusage, archiver, @modelcontextprotocol/sdk. C'est tout.
+
+## Développement
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Licence
+
+MIT
+
+---
+
+Créé par <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>