Skip to main content

AI Footprint

🌐 Site officiel — présentation, installation et documentation en ligne.

Connaître l'empreinte environnementale de tes sessions d'IA. AI Footprint (ai-footprint) lit les transcripts de Claude Code, Opencode, Pi et Codex CLI, estime l'impact de chaque réponse générée, et te le restitue sous forme de rapport et de suivi en temps réel — directement dans l'outil que tu utilises déjà.

Le calcul n'est pas réinventé : il est délégué à EcoLogits, un moteur reconnu, offline et multi-critères.

Ce qu'on mesure

Pas seulement le CO₂. Cinq critères, chacun donné en fourchette (pas un faux chiffre précis — voir « Pourquoi des fourchettes ») :

Critère Ce que ça représente
🌍 GWP gaz à effet de serre (kg CO₂eq)
💧 Eau eau consommée (L)
⛏ ADPe épuisement des métaux/ressources (kg Sbeq)
⚡ Énergie électricité (kWh)
🔥 PE énergie primaire (MJ)

Pourquoi des fourchettes ? La région exacte des datacenters d'Anthropic (donc leur mix électrique) est inconnue, et le rendement d'un datacenter (PUE) varie. Cette incertitude est irréductible : on l'affiche (min–max + valeur centrale ~) plutôt que de la cacher. Détails : docs/METHODOLOGY.md.

Installation

Rapide (une ligne)

curl -fsSL https://raw.githubusercontent.com/hrenaud/ai-footprint/main/install.sh | bash

L'installeur détecte Python ≥ 3.10, installe ai-footprint + EcoLogits, expose la commande ai-footprint, déploie les skills et câble le suivi (statusline + ingestion) pour chaque outil détecté sur ta machine — Claude Code, Opencode (plugin), Pi (extension) et Codex CLI — et fait un backfill initial de leurs sessions locales. Redémarre ton outil ensuite pour activer les skills.

Options d'installation (variables d'environnement) et détails complets : voir le guide avancé.

Via Homebrew (macOS/Linux)

brew install hrenaud/tap/ai-footprint

Via PyPI

pip install ai-footprint

Homebrew et PyPI n'installent que la CLI (ai-footprint), sans câblage automatique dans ton outil (pas de statusline, pas d'ingestion, pas de skills). Pour l'intégration complète, utilise l'installeur rapide ci-dessus, ou câble-la toi-même — voir le guide avancé.

Manuelle (dev)

Python ≥ 3.10, puis depuis un clone du dépôt : pip install -e ..

Désinstallation

curl -fsSL https://raw.githubusercontent.com/hrenaud/ai-footprint/main/uninstall.sh | bash

Retire le binaire, les skills, le câblage dans chaque outil (statusline + hook d'ingestion Claude Code, plugin Opencode, extension Pi, backfill Codex CLI) et le répertoire source. La base ai-footprint.db (historique d'impact) est conservée par défaut — ajoute AI_FOOTPRINT_PURGE_DB=1 avant la commande pour la supprimer aussi.

Utilisation — via les skills (recommandé)

C'est la façon recommandée d'utiliser ai-footprint : tape la commande slash, ou demande simplement en langage naturel (les skills se déclenchent aussi sur des formulations comme « mon impact » ou « mon empreinte CO₂ ») :

Skill À quoi ça sert Exemple
/footprint-report Ton rapport d'impact complet. « mon impact », « mon empreinte CO₂ »
/footprint-card Une card PNG partageable (1080×1080) résumant ton empreinte. « exporte mon empreinte en image »
/footprint-resolve Estimer l'impact de modèles tiers/locaux non reconnus (les associe à un modèle Hugging Face). quand le rapport liste des « modèles non couverts »
/footprint-config Régler ta zone électrique (ex. France) et les paramètres datacenter. « configure ma zone élec »
/footprint-help Aide : toutes les commandes et options. « comment utiliser ai-footprint »

Le rapport a cinq sections : impact total, projets les plus impactants, tokens & impact par modèle, modèles non couverts, et intensité par modèle (impact par heure de travail — révèle qu'à débit égal, Opus émet bien plus que Haiku). Une sixième section, intensité par outil, apparaît automatiquement dès que tes données couvrent plusieurs outils (Claude Code, Opencode, Pi, Codex CLI…) — elle révèle quel outil consomme le plus de tokens et a les impacts les plus forts, à débit égal.

Options utiles du rapport : --since 2026-06-27 (ou 27/06/26) pour une période, --detail pour les fourchettes min–max par modèle/projet, --all-projects pour la liste complète. /footprint-help (ou ai-footprint report --help) les liste toutes.

Card partageable

/footprint-card exporte une image PNG 1080×1080 résumant ton empreinte : le carbone (GWP) en héro, les 4 autres critères (eau, énergie, ADPe, énergie primaire) en tuiles, et le top 3 des projets les plus impactants. Chaque valeur est posée sur sa fourchette min–max via une jauge à marqueur central — la signature visuelle du projet, pour ne jamais présenter un chiffre unique trompeur.

Nécessite Chrome ou Chromium installé localement (rendu HTML → PNG en headless, aucune dépendance Python supplémentaire). Options : --since, --theme light|dark|both (défaut light), --lang fr|en|both (défaut both), --out (défaut ~/.ai-footprint/exports/).

Suivi en temps réel

Dans Claude Code, l'impact s'affiche dans la statusline. Dans OpenCode, une carte dédiée s'affiche dans le panneau latéral.

Une fois l'installation terminée, ton outil affiche en continu l'impact de la session en cours (l'outil transmet la session ; ai-footprint ingère le transcript courant et filtre dessus). En lancement manuel, hors session, ça retombe sur le total global :

~/.ai-footprint/src/scripts/statusline.sh   # ⚡ 18.9–33.5 kWh · 🌍 7.93–13.5 kgCO2e · 💧 61.3–134 L

L'installeur ne remplace jamais une statusline déjà utilisée par un autre outil — il affiche alors la commande pour basculer manuellement.

Un préfixe ≈ (suivi d'un rappel entre parenthèses, ex. sonnet-5 inconnu, params sonnet-4) signale que la session utilise un modèle trop récent pour le registre EcoLogits : l'impact affiché est un repère provisoire, extrapolé des paramètres officiels de la version sœur nommée — voir docs/METHODOLOGY.md.

En ligne de commande (sous le capot)

Les skills appellent simplement la CLI ; tu peux l'utiliser directement :

ai-footprint ingest      # parse les transcripts → base SQLite (~/.ai-footprint/ai-footprint.db)
ai-footprint report      # rapport multi-critères (--since, --detail, --all-projects)
ai-footprint card        # card PNG partageable (--since, --theme, --lang, --out)
ai-footprint statusline   # ligne compacte
ai-footprint resolve --list   # modèles non couverts à résoudre

ingest résume la couverture, p. ex. :

80 events ingérés · 33639/33709 mesurés · 70 non couverts (conservés, impact non estimé)

Les « non couverts » sont des modèles hors périmètre EcoLogits — l'event est conservé mais exclu des totaux (afficher un faux chiffre serait pire). Beaucoup sont des placeholders internes <synthetic> (0 token) ; les vrais modèles tiers se résolvent avec /footprint-resolve. Voir docs/METHODOLOGY.md.

Lorsqu'un transcript ne permet pas d'identifier sa route avec certitude, ai-footprint conserve son indice d'origine sans le prendre pour une confirmation. /footprint-resolve confirme ensuite la route et le modèle d'un lot choisi ; les routes de service tiers openrouter et custom restent volontairement non estimées.

Pour aller plus loin

  • docs/GUIDE.md — mode d'emploi détaillé : installation, désinstallation, usage complet des skills et de la CLI.
  • docs/GUIDE-AVANCE.md — installation manuelle (Homebrew, PyPI, sources), variables d'environnement, fonctionnement interne.
  • docs/METHODOLOGY.md — comment l'impact est évalué : les échanges avec EcoLogits, les choix de méthodologie et leurs limites.
  • docs/CONTRIBUTING.md — côté technique : architecture, schéma de données, mise en place dev et comment étendre le projet.

Sources d'inspiration

  • EcoLogits (mlco2/ecologits) — le moteur d'impact (offline, multi-critères/phases).
  • claude-carbon — audit d'origine et UX de reporting.
  • CodeCarbon — tracker offline, zone électrique par code pays.
  • thirsty-llm — approche offline-first et fourchettes (on en rejette le modèle prix-proxy, remplacé par EcoLogits).

Metadata

Release files for ai-footprint 1.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-footprint 1.11.0
File Size Uploaded Provenance Actions
ai_footprint-1.11.0.tar.gz 119.1 kB With provenance Details for ai_footprint-1.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-footprint 1.11.0
File Interpreter ABI Platform Actions
ai_footprint-1.11.0-py3-none-any.whl Python 3 none any Details for ai_footprint-1.11.0-py3-none-any.whl

Total release size: 197.8 kB

Release files / ai_footprint-1.11.0.tar.gz

Download URL ai_footprint-1.11.0.tar.gz
Size 119.1 kB
Tags Source
SHA-256 checksum
How to use checksums
695f3b293c92d8225d2e32c04ce0f4ee86ae3df51845098e96277d49a18c982f
BLAKE2b-256 checksum
How to use checksums
b6b11bce3b183b5c8cc6724bc36049284b49843bfa121711d07d733cf09e27d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.

Transparency log

Release files / ai_footprint-1.11.0-py3-none-any.whl

Download URL ai_footprint-1.11.0-py3-none-any.whl
Size 78.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7b5e463bbccc73e1a3ba7dc22d9f36afd2eae13bb0764d6947801aaa581cc2a
BLAKE2b-256 checksum
How to use checksums
225ea981ae327863f424a04c076415cb1ce193c94b2554dd81a0e906f95d00ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.

Transparency log

Security for ai-footprint 1.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ai_footprint-1.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page