🌿 GreenCode

Measure the carbon footprint of your code. Get a live badge for your README.

One GitHub Action. One badge. Every push — your CO₂ tracked automatically.

pip install greencode
greencode measure

---

Why?

Every time your tests run, your CI consumes electricity → produces CO₂. Most developers have no idea how much. GreenCode makes it visible.

• 🌿 4.2g CO₂ — your test suite per run
• 🔥 87g CO₂ — after a careless dependency bump
• 📈 +340% — what that new ML model added

---

Quick Start

1. Install

pip install greencode

2. Measure

# Measure while running your tests
greencode measure

# With a custom command
greencode measure --command "python -m pytest tests/ -x"

# Output as JSON (for CI integration)
greencode measure --json

Output:

╭─────────────────────────────────────────╮
│         GreenCode Measurement           │
│                                         │
│  Project:  mylib                        │
│  Commit:   a3f9c2d  (main)              │
│  CO₂:      🌿 4.2100 g  (0.00000421 kg) │
│  Grade:    GREEN — low carbon           │
│  Method:   measured                     │
│                                         │
│  vs prev:  ▼ 0.8g (-16.0%)             │
╰─────────────────────────────────────────╯

Badge saved → .greencode/badge.svg
Add to README:
[![Carbon Footprint](https://greencode.dev/badge/you/mylib.svg)](https://greencode.dev)

3. Add the badge to your README

[![Carbon Footprint](https://greencode.dev/badge/YOUR_USERNAME/YOUR_REPO.svg)](https://greencode.dev)

It updates automatically on every push. 🎯

---

GitHub Action

Add to .github/workflows/carbon.yml:

name: Carbon Footprint

on: [push, pull_request]

jobs:
  measure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: greencode-dev/greencode@v1
        with:
          country: DEU        # Your server's country (emission factors)
          comment-on-pr: true # Post CO₂ report as PR comment

What it does on every push:

• Runs your tests while measuring CO₂
• Updates .greencode/badge.svg in your repo
• Posts a comment on PRs showing the delta vs main

PR Comment:

## 🌿 Carbon Footprint Report

| Metric | Value     |
|--------|-----------|
| CO₂    | 4.2100g   |
| Grade  | GREEN     |
| Commit | a3f9c2d   |

> This PR: ▲ +2.3g CO₂ (+15% vs main)

---

Badge grades

Badge	Threshold	Meaning
🌿 green	< 10g CO₂	Low carbon — well optimized
🌡 yellow	10–50g CO₂	Moderate — room to improve
🔥 red	> 50g CO₂	High carbon — needs attention

---

Commands

greencode measure              # Measure + save badge
greencode measure --json       # Raw JSON output
greencode badge                # Regenerate badge from latest
greencode history              # Show measurement history
greencode history --limit 20   # Last 20 measurements

---

Configuration

Create greencode.toml in your project root:

[greencode]
country    = "DEU"        # ISO 3166-1 alpha-3 country code
command    = "pytest ."   # Custom test command
badge_path = ".greencode/badge.svg"

Supported country codes for emission factors: DEU · USA · GBR · FRA · CHN · RUS · + 40 more →

---

Output files

After running greencode measure:

.greencode/
├── badge.svg      # Your live badge (commit this!)
├── latest.json    # Most recent measurement
└── history.json   # All measurements (last 100)

Add .greencode/badge.svg and .greencode/latest.json to git.
Add .greencode/history.json to .gitignore or commit it — your choice.

---

How it works

GreenCode uses CodeCarbon under the hood to measure:

1. Power consumption — tracks CPU/GPU watts during your test run
2. Emission factor — converts kWh → kg CO₂ using your country's grid mix
3. Badge — generates a live SVG badge with the result

The measurement is a relative baseline, not a certified carbon audit.
It's useful for tracking trends and comparing PRs — not for ESG reporting.
For certified reporting, see our Enterprise plan →

---

Methodology

CO₂ (kg) = Power (kW) × Duration (h) × Emission Factor (kg CO₂/kWh)

Emission factors by country:
  Germany (DEU): 0.366 kg CO₂/kWh
  USA:           0.386 kg CO₂/kWh
  France (FRA):  0.056 kg CO₂/kWh  ← nuclear
  China (CHN):   0.555 kg CO₂/kWh

Full methodology: greencode.dev/docs/methodology

---

Contributing

git clone https://github.com/greencode-dev/greencode
cd greencode
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for guidelines.
Good first issues: github.com/greencode-dev/greencode/issues?q=good+first+issue

---

Roadmap

• CLI: greencode measure
• Badge generator
• GitHub Action
• Web dashboard: greencode.dev/dashboard
• Leaderboard: top 50 greenest open source projects
• PR comparison: this PR vs main (CO₂ delta)
• More languages: Node.js, Go, Rust native hooks
• Enterprise: certified ESG reporting

---

License

MIT © greencode-dev

---

greencode.dev · Docs · Issues