Green Claude: digital sobriety for Claude Code

🇫🇷 Lire en français

Green Claude is a skill for Claude Code that guides Claude toward eco-designed code, automatically, with no command to remember.

Built by the Institut du Numérique Responsable (French non-profit on responsible digital practices), 2026, MIT licensed.

Eco-designed code = fewer resources consumed by every user, on every run, for the software's entire lifetime.

This repository is specific to Claude Code. A standalone, portable version of the rules — usable with other AI assistants and other languages — is in development here: regles-ecoconception-ia.

In one sentence

Install the skill once. From then on, whenever Claude Code writes or reviews code in your projects, it applies eco-design rules on its own (RGESN 2024, GR491, Green Software Foundation, W3C Web Sustainability Guidelines, plus thresholds drawn from YellowLabTools), without you having to ask each time.

Why a skill instead of a plain rule list

An RGESN checklist in a PDF or wiki depends on someone remembering to reopen it. Nobody reads it again before every line of code, and how well it's followed varies from person to person, and from day to day.

A Claude Code skill makes three concrete differences:

• Loads automatically every session. The skill loads itself — no need to mention it at the start of a conversation.
• Contextual rule selection. Claude applies whichever families are relevant to what it's writing right now: a backend file triggers the SQL and connection-pool rules, not the UX/UI rules about autoplay.
• Built-in after-the-fact verification. The audit script (eco-audit.sh) runs on demand against code already written, at zero reasoning cost for the model, to catch what proactive application missed.

A checklist stays a document you consult. The skill runs at the moment the code is written, inside the working session itself.

Installation

Via the Claude Code plugin manager (recommended)

/plugin marketplace add Institut-du-Numerique-Responsable/green-claude
/plugin install green-claude@green-claude

Claude Code then handles updates (/plugin update green-claude) without a manual git pull.

Via install.sh

git clone https://github.com/Institut-du-Numerique-Responsable/green-claude.git
cd green-claude
./install.sh

This installs the skill into ~/.claude/skills/green-claude. Nothing else to do: Claude Code loads it automatically in your next sessions. This method is still worth using if you also want the optional cache hooks (see below), which the plugin manager doesn't wire up on its own.

Prerequisite: jq, needed by the audit script and the hooks (brew install jq / sudo apt install jq).

Usage

Nothing to type. Three ways to use it:

The audit (skills/green-claude/scripts/eco-audit.sh) is a deterministic script (grep against the rules): it costs the model no reasoning, only the reading of the result.

Real example

This entirely ordinary piece of code:

import _ from 'lodash';

app.get('/api/users', (req, res) => {
  db.query('SELECT * FROM users', (err, rows) => {
    res.json(rows);
  });
});

eco-audit.sh api.js (real, unedited output):

[High] ECO-FRONT-01 — Avoid heavy libraries for minor needs
  Recommendation: Prefer native language functions or lightweight alternatives (date-fns, Alpine.js).

[High] ECO-BACK-01 — Optimize SQL queries
  Recommendation: Select only the columns you need, index filtered columns, avoid functions in WHERE clauses and N+1 queries.

2 eco-design issue(s) detected.

In practice, you don't need to run the audit yourself on code like this: in proactive mode, Claude avoids lodash for a single function and SELECT * right when writing the code, before any audit even happens.

Installing natively in Claude

Three channels, three formats. Claude Code needs nothing more than the repository:

/plugin marketplace add Institut-du-Numerique-Responsable/green-claude
/plugin install green-claude

The other two want a zip archive, which package-skill.sh builds:

bash skills/green-claude/scripts/package-skill.sh    # writes into dist/

The two archives hold the same skill and differ only by the description: Claude.ai caps it at 200 characters where the API allows 1024. The repository keeps the long one, which is what makes Claude Code load the skill at the right moment; the packaging script substitutes a short version rather than truncating mid-sentence, since a sentence cut in half triggers badly.

The audit script needs bash and jq. Where jq is missing, the rules still apply while Claude writes code — only eco-audit.sh stops working.

The rules: 52 rules aligned with the 9 RGESN 2024 families

skills/green-claude/rules/ecoconception.json covers all 9 families of RGESN 2024 (78 official criteria). Each rule references the matching RGESN criterion (rgesn_ref) and GR491 family (gr491_famille):

Rules with no detectable pattern (process, governance) are skipped by the audit and serve as a checklist in /green-claude.

Language rules: 80 rules loaded on demand

The 52 rules above hold whatever the language. They set the goal without saying how to reach it in Python or in Java: "avoid N+1 queries" doesn't choose between select_related, JOIN FETCH, Include and with().

skills/green-claude/rules/langages/ goes one level down, with one file per language, applied only to files of that language:

Without this filtering by extension, one language's patterns fire on the others: .all(), save() and += exist everywhere and don't point at the same problem. The audit only loads the file for the languages actually present among its arguments.

eco-audit.sh --list-langs           # covered languages and their globs
eco-audit.sh --list-rules python    # full checklist for one language

Measure, don't assume

eco-score.sh counts the patterns found in a repository, weights them by impact and reports them against code volume:

skills/green-claude/scripts/eco-score.sh          # human-readable
skills/green-claude/scripts/eco-score.sh --json   # one line per measurement, to keep over time

This score counts known patterns, not joules. A falling density says the code holds fewer recognizable patterns, not that it draws less power. Compare it to last month's rather than to zero, and check it against a real runtime measurement (query count, bytes transferred, CPU time, EcoIndex on a page): that's what settles it.

Two more checkpoints, both optional:

• hooks/green-claude-pre-commit.sh audits staged files. Where the Claude Code hook only sees what Claude writes, this one also sees what you write. It reports without blocking, unless you pass GREEN_CLAUDE_STRICT=1.
• .github/workflows/eco-audit.yml runs the rule test suite on every PR and publishes the repository's density in the job summary.

Boris's practices: using Claude soberly and sensibly

Coding with AI also has a cost during the session itself: every request consumes energy. Boris Cherny, Claude Code's creator, documents efficient usage practices. Efficient use is also sober use: every avoided back-and-forth saves tokens, every trimmed context does too.

skills/green-claude/rules/boris.json picks up 14 of them, including two added with verified open-source tool examples:

Full detail: skills/green-claude/rules/boris.json.

The third-party tools cited (graphify, caveman) are verified illustrative examples (open source, MIT license). The project doesn't audit them and doesn't depend on them.

What a skill can't do (and how it's covered anyway)

A skill runs during a session that's already started, and the model decides whether to apply it. So it can't pick the starting model, can't intercept a call before it leaves, and can't guarantee a rule gets checked every single time. Three levers therefore live outside the skill, in hooks/, optional and offered at install time:

• Systematic audit (hooks/green-claude-audit.sh): wired as PostToolUse on Write|Edit|MultiEdit. Claude Code runs it after every code file written, without asking the model. It audits what was just added and hands the findings back to Claude, who fixes them before moving on.
• Local cache (hooks/green-claude-cache.sh): a question already asked gets served again without calling the model — zero tokens spent.
• Off-peak warning (same hook): flags peak hours (outside 22:00-06:00 UTC) without ever blocking.

These hooks wire into ~/.claude/settings.json. If you answer "y", install.sh adds them there (other settings are preserved, and a backup of the original file is left at settings.json.green-claude.bak). Without jq, it prints the config to paste in by hand. To remove them: delete the green-claude-* entries from the file.

Writing your own rules

Add a JSON file under skills/green-claude/rules/, structured like ecoconception.json (categories → rules):

{
  "id": "CUSTOM-001",
  "title": "My rule",
  "impact": "High",
  "patterns": ["my_regex_pattern"],
  "recommendation": "What to do instead."
}

• patterns: grep -E regular expressions detecting the problem. Empty list = a practice (checklist item, skipped by the audit).
• impact: High, Medium, or Low.
• rgesn_ref / gr491_famille (optional): pointer back to the official standards.
• detector / enrich (optional): for cases a pattern alone can't see (multi-line nesting, counting, the real weight of a referenced file...), a dedicated script under scripts/. Full detail in CONTRIBUTING.md.
• note (optional): a caveat shown in the audit's own output (known false positive, threshold, limited scope) — this is where to document a rule's interpretation pitfalls, not in the skill itself.

Then re-run ./install.sh to republish the updated skill.

🤝 Contributing

1. Fork this repository
2. Create a branch (git checkout -b feature/my-rule)
3. Add your rules or improvements (jq empty skills/green-claude/rules/*.json to validate the JSON)
4. Open a Pull Request

Most useful contributions: new audit rules sourced from RGESN, GR491, GSF, WSG, or another recognized public reference, with their rgesn_ref; pattern fixes (false positives); translations.

Full detail on the rule format and PR process: CONTRIBUTING.md.

🙏 References

• RGESN 2024: Référentiel Général d'Écoconception de Services Numériques (78 criteria, 9 families)
• GR491: reference guide for responsible digital service design (61 recommendations, 516 criteria)
• Green Software Foundation: software eco-design patterns
• W3C Web Sustainability Guidelines: web sustainability guidelines (UX, development, hosting, strategy)
• YellowLabTools: open-source front-end quality audit tool, source of several thresholds (DOM, CSS, fonts)
• How Boris uses Claude Code: Boris Cherny's practices, Claude Code's creator
• Anthropic: Claude and Claude Code

Maintainers

• Guillaume Gallon (LinkedIn) — Institut du Numérique Responsable

📄 License

MIT, © 2026 Institut du Numérique Responsable