ByteThirst CLI

Estimate 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

See it in action — bytethirst demo

Run a hardcoded sample workflow ("Summarize the React docs" on gpt-4-turbo) through the local calculation engine. No network, no signup, completes in under 8 seconds. Shows water/energy/CO₂ estimates with explicit ± ranges, then a comparison panel against a smaller model.

bytethirst demo

# JSON output for scripting
bytethirst demo --json

Wrap a CLI AI tool

# Estimate a Claude Code session
bytethirst exec -- claude

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

# Estimate 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.
------------------------------------------

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

The exec wrapper only estimates CLI sessions. To estimate 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-agent | bytethirst exec -- cursor-agent | | cursor (legacy alias) | bytethirst exec -- cursor | | copilot ... | bytethirst exec -- copilot ... | | gh copilot ... | bytethirst exec -- gh copilot ... |

Both the new standalone copilot binary (v1.0.51+, May 2026) and the legacy gh copilot extension (deprecated Oct 2025) 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 |

Crash reports (opt-in)

ByteThirst CLI can upload crash reports to Sentry to help us catch bugs that didn't surface in testing. Off by default — nothing is uploaded until you explicitly turn it on.

# Check current setting (default: off)
bytethirst config sentry status

# Opt in
bytethirst config sentry on

# Opt out
bytethirst config sentry off

When enabled, only crash data is uploaded:

• Stack traces with ~/.bytethirst/ paths sanitized out
• The command you ran (bytethirst calc, bytethirst exec, etc.) and its exit code
• Error message and CLI version

Never uploaded: the content of your AI prompts or responses, your auth tokens, your Firebase UID, file contents, or environment variables. The opt-in state is stored at ~/.bytethirst/sentry.json and persists across CLI upgrades.

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 (standalone) | copilot | Yes | | GitHub Copilot CLI (legacy gh copilot) | 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 state ledger

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 local-first by default. Tracked sessions and badges live in ~/.bytethirst/. No Firestore sync until you explicitly run bytethirst login, bytethirst sync, or bytethirst config cloud-sync true.
• The CLI never reads, stores, or transmits the content of your AI prompts, responses, or any file content. The wrapper measures input/output by character count only and never inspects the text. This is enforced in code by the privacy lint test in our test suite.
• 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.
• Anonymous usage events. The CLI sends a small set of structured events to PostHog (our product-analytics service) to help us measure activation and improve the product. Each event carries: an anonymous install ID (a random UUID stored at ~/.bytethirst/install_id), the surface (ide), the CLI version, the event name (e.g. install, first_command_run, session_tracked), and environmental-estimate metadata (water/energy/CO₂ figures and the methodology version they were computed under). After you sign in, your Firebase user ID is added so events from your CLI, browser extension, and dashboard merge into one view. Never sent: prompt content, response content, file contents, account credentials, IP address (anonymized at ingest), or anything that identifies you to the network.
• Opt out of anonymous usage events with bytethirst config telemetry off. Status: bytethirst config telemetry status. Re-enable: bytethirst config telemetry on. The CLI also honors BYTETHIRST_NO_TELEMETRY=1 and CI=true as environment-variable opt-outs (CI is opt-out by default).
• Crash reporting via Sentry is opt-in and off by default. Run bytethirst config sentry on to enable; see the Crash reports (opt-in) section above for what is and isn't uploaded. The Google Analytics + Ketch CMP that run 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. Opting out via config telemetry off writes ~/.bytethirst/telemetry.json with { "enabled": false }; this file is read on every event call so the opt-out takes effect immediately.
• See bytethirst whoami to check what account (if any) you're signed in as, and bytethirst logout to sign out.
• Public methodology. Every environmental number the CLI displays is an estimate, computed under a versioned methodology you can read at bytethirst.com/methodology. Estimates carry explicit ± ranges and are pinned to the methodology version in effect at measurement time.

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.