npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

bytethirst

v0.2.15

Published

CLI companion for ByteThirst — estimate AI environmental impact from the terminal

Downloads

2,362

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

bytethirstbytethirst

Keywords

aienvironmentalwaterenergyco2climatesustainabilitycli

Readme

ByteThirst CLI

Track the environmental impact of your AI tool usage from the terminal. Water, energy, and CO2 estimates for Claude Code, Aider, GitHub Copilot CLI, Cursor, OpenAI Codex, and more.

Companion to the ByteThirst Chrome Extension -- syncs to the same account so browser and terminal usage appear in one dashboard.

Install

npm install -g bytethirst

Requires Node.js 18+.

Quick Start

Wrap a CLI AI tool

# Track a Claude Code session
bytethirst exec -- claude

# Track an Aider session
bytethirst exec -- aider --model claude-3.5-sonnet

# Track GitHub Copilot CLI
bytethirst exec -- gh copilot suggest

# Force a specific adapter
bytethirst exec --adapter codex -- codex

After the session ends, ByteThirst prints an impact summary:

--- ByteThirst(TM) Session Summary -------
  est. 8.4 mL water (~ 1.7 tsp)
  ~ 0.21 Wh energy
  ~ 0.08 g CO2
  Queries: 3 . Platform: claude . Model: sonnet (standard)
  QueryWeight(TM) values are estimates.
------------------------------------------

Track Claude Code everywhere (VS Code, Desktop, Web)

The exec wrapper only tracks CLI sessions. To track Claude Code across all surfaces — VS Code extension, Desktop app, and web — install the SessionEnd hook:

# One-time setup
bytethirst hook install

# Verify it's active
bytethirst hook status

This adds a hook to ~/.claude/settings.json that runs automatically when any Claude Code session ends. It reads the session transcript for exact token counts — no PTY wrapping needed.

# See what the hook config looks like
bytethirst hook show

# Remove the hook
bytethirst hook uninstall

You can also ingest a transcript manually:

bytethirst ingest --transcript /path/to/transcript.jsonl

Tip: Use bytethirst hook install alongside bytethirst alias install for complete coverage. The hook handles VS Code/Desktop/Web; the alias handles terminal sessions with the PTY wrapper for real-time display.

Standalone calculator

# Estimate impact from token counts
bytethirst calc --tokens 5000 --platform claude --model opus

# With explicit input/output split
bytethirst calc --input-tokens 750 --output-tokens 4250 --platform chatgpt --model gpt-4o

# JSON output for scripting
bytethirst calc --tokens 10000 --platform claude --model standard --json

View your data

# Today's totals
bytethirst status

# Specific date
bytethirst status --date 2026-04-03

# Recent history (table)
bytethirst history --days 14

# Export as CSV
bytethirst history --days 30 --format csv > impact.csv

Authentication

Sign in with the same account as the Chrome extension to sync data.

# Interactive menu (Google, Microsoft, or Email)
bytethirst login

# Direct methods
bytethirst login --google
bytethirst login --microsoft
bytethirst login --email

# Create a new account
bytethirst signup

# Check who you're signed in as
bytethirst whoami

# Sign out
bytethirst logout

# Password reset
bytethirst login --reset

Cloud Sync

Personal cloud sync (any user)

Sync your data across devices — see CLI usage in the extension popup and the web dashboard at bytethirst.app. Opt-in, off by default.

# Enable personal cloud sync
bytethirst config cloud-sync true

# Disable (optionally delete cloud data)
bytethirst config cloud-sync false

When enabled, data syncs automatically after each exec and ingest session. Your daily query counts and impact estimates are stored in your ByteThirst account. No prompts, responses, or conversation content is ever stored.

Team sync

# Sync today's data to team Firestore
bytethirst sync

# Sync a specific date
bytethirst sync --date 2026-04-01

# Sync all unsynced dates
bytethirst sync --all

Team sync runs automatically after exec sessions when signed in and on a team (auto-sync config).

Automatic Aliases

Run bytethirst alias install to set up shell aliases so your AI tools always run through ByteThirst:

# Install aliases (adds to ~/.bashrc, ~/.zshrc, or fish config)
bytethirst alias install

# Now typing `claude` automatically estimates impact
claude

# See what aliases would be added
bytethirst alias show

# Remove aliases
bytethirst alias uninstall

# Specify shell explicitly
bytethirst alias install --shell zsh

After installing, these commands are aliased automatically:

| You type | Runs | |----------|------| | claude | bytethirst exec -- claude | | aider | bytethirst exec -- aider | | codex | bytethirst exec -- codex | | cursor | bytethirst exec -- cursor | | gh copilot ... | bytethirst exec -- gh copilot ... |

gh copilot commands are wrapped automatically. Other gh commands (PRs, issues, etc.) pass through unchanged.

Configuration

# Show all settings
bytethirst config

# Get a value
bytethirst config default-platform

# Set a value
bytethirst config default-model large
bytethirst config auto-sync false

| Key | Default | Description | |-----|---------|-------------| | default-platform | claude | Default platform for calc | | default-model | standard | Default model tier for calc | | auto-sync | true | Auto-sync to team after exec sessions | | cloud-sync | false | Personal cloud sync across devices (opt-in) | | display-mode | midpoint | Show mid estimate only |

Badges

Earn badges for sustainable AI usage. 21 badges total (6 free + 15 premium). Badges sync across devices when cloud sync is enabled.

# View earned badges and progress
bytethirst badges

# JSON output
bytethirst badges --json

Badges are evaluated automatically after each exec and ingest session. Examples:

| Badge | Criterion | |-------|-----------| | First Drop | 1+ lifetime query | | Half Century | 50+ lifetime queries | | Lighter Footprint | 10% weekly usage reduction | | Streak Master | 4 consecutive decrease weeks | | Efficient Week | >50% queries used small-tier models | | Footprint Aware | 30+ CLI sessions |

Supported Tools

| Tool | Command | Auto-detected | |------|---------|---------------| | Claude Code | claude | Yes | | Aider | aider | Yes | | GitHub Copilot CLI | gh copilot | Yes | | Cursor | cursor | Yes | | OpenAI Codex | codex | Yes |

How It Works

PTY wrapper (bytethirst exec)

  1. bytethirst exec wraps your AI tool in a pseudo-terminal (PTY)
  2. All I/O passes through transparently -- your tool works normally
  3. ByteThirst counts characters, strips ANSI codes, estimates tokens
  4. Token counts are converted to water/energy/CO2 using the same calculation engine as the Chrome extension
  5. Results are stored locally in ~/.bytethirst/data/ and optionally synced to Firebase

Claude Code hook (bytethirst hook install)

  1. A SessionEnd hook fires when any Claude Code session ends
  2. Claude Code passes the transcript file path to bytethirst ingest via stdin
  3. ByteThirst parses the JSONL transcript for API request events with exact token counts
  4. Impact is calculated and recorded to the same local store
  5. Works across all Claude Code surfaces: CLI, VS Code, Desktop app, and web

Estimation Methodology

All values are estimates based on published research. The calculation uses:

  • Anchor: 100 input + 500 output tokens (standard tier) = 0.30 Wh
  • Model tiers: small (0.3x), standard (1.0x), large (2.5x), reasoning (5.0x)
  • Water: 0.5-1.2 mL per Wh (varies by data center cooling)
  • CO2: 0.20-0.60 g per Wh (varies by grid carbon intensity)

See bytethirst.com/methodology for full details.

Data Storage

Local (always, no opt-in needed):

  • ~/.bytethirst/data/day_YYYY-MM-DD.json — daily usage records
  • ~/.bytethirst/badges.json — earned badges
  • ~/.bytethirst/streaks.json — streak and progress data
  • ~/.bytethirst/auth.json — Firebase auth credentials
  • ~/.bytethirst/config.json — preferences
  • ~/.bytethirst/sync-state.json — sync tracking

Cloud (opt-in only, cloud-sync true):

  • /users/{uid}/dailyData/{date}_cli — daily aggregates in Firestore
  • /users/{uid}/badges/tracker — earned badges (synced across devices)
  • /users/{uid}/badges/streaks — streak data (synced across devices)

Privacy & Terms

ByteThirst CLI is part of the ByteThirst product family. By installing or using the CLI you agree to:

  • Terms of Service — what you can and can't do with ByteThirst products, including the open-source CLI's AGPL-3.0 source rights and the trademark restrictions on forks
  • Privacy Policy — what data we collect, when, and from which surface (the CLI itself never collects conversation content or prompts)

Quick privacy summary for the CLI:

  • The CLI runs fully local by default. No network calls until you explicitly run bytethirst login, bytethirst sync, or bytethirst config cloud-sync true.
  • After sign-in, the CLI authenticates against Firebase Auth and may call ByteThirst Cloud Functions to sync daily aggregates, badges, and team data — same backend as the Chrome extension.
  • The CLI never reads, stores, or transmits the content of your AI prompts or responses. Only token counts, model tier, platform name, and date.
  • The CLI does not use Google Analytics, telemetry, or any third-party tracker. The Ketch CMP and GA4 used on bytethirst.com do not run inside the CLI.
  • Local data lives in ~/.bytethirst/. You can delete it at any time. Uninstalling the npm package does not auto-delete it.
  • See bytethirst whoami to check what account (if any) you're signed in as, and bytethirst logout to sign out.

Run bytethirst --version to see your installed version. The CLI sends _clientName: "cli" and _clientVersion with every Cloud Function call so the server can enforce a minimum supported version.

License

ByteThirst CLI is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). The full license text is in the LICENSE file in this package.

You may use, study, modify, and redistribute the CLI source code under the terms of the AGPL. If you run a modified version of the CLI as a network service, AGPL Section 13 requires you to make the modified source available to users of that service.

The ByteThirst™ and QueryWeight™ trademarks are not included in the AGPL grant. Forks must remove or replace ByteThirst branding (package name, command name, user-facing copy, documentation) before redistribution. See Section 6 of the Terms of Service for details.

The Chrome extension, team dashboard (bytethirst.app), marketing site (bytethirst.com), and Cloud Functions backend are not open-source and remain proprietary to ByteThirst.