CLI — ByteThirst

See It in Action

ByteThirst wraps your AI tool transparently — everything works exactly as normal. When your session ends, you see this:

Terminal

$ bytethirst exec -- claude
ByteThirst™ estimating: claude-code · claude · sonnet (standard)

... your Claude Code session runs normally ...

——— ByteThirst™ Session Summary ———————————————————————————
  💧 est. 0.1 mL
  ⚡ ≈ 0.06 Wh energy
  🌍 ≈ 0.02 g CO₂
  Queries: 1 · Platform: claude · Model: sonnet (standard)
  QueryWeight™ values are estimates.
————————————————————————————————————————

Install

Requires Node.js 18+. One command, globally available.

npm install -g bytethirst

How It Works

1

Wrap your tool

bytethirst exec spawns your AI tool inside a pseudo-terminal (PTY). All I/O passes through transparently — colors, cursor movement, line editing, everything works exactly as normal.

2

Estimate impact

ByteThirst counts output characters, strips ANSI codes, estimates tokens using platform-specific ratios, and calculates water, energy, and CO₂ using the same engine as the Chrome extension.

3

Sync to dashboard

Sign in with the same Google, Microsoft, or email account. Terminal and browser usage appear in one unified team dashboard.

Supported Tools

Auto-detected from the command name. Override with --adapter for any tool.

🤖

Claude Code bytethirst exec -- claude

👨‍💻

Aider bytethirst exec -- aider

🐙

GitHub Copilot CLI bytethirst exec -- gh copilot suggest

🖱️

Cursor bytethirst exec -- cursor

⚡

OpenAI Codex bytethirst exec -- codex

+

Any CLI tool bytethirst exec --adapter …

Commands

bytethirst exec -- claudeWrap an AI tool and estimate impact

bytethirst calc --tokens 5000 --platform claude --model opusStandalone impact calculator

bytethirst statusView today’s totals

bytethirst history --days 14Recent history (table, JSON, or CSV)

bytethirst loginSign in — Google, Microsoft, or Email

bytethirst sync --allPush data to your team dashboard

bytethirst configView or set preferences

bytethirst whoamiShow current signed-in user

bytethirst alias installAuto-alias claude, aider, codex to run through ByteThirst

Cross-Device Sync

Enable cloud sync to see your CLI and Chrome extension data in one place — the extension popup, the web dashboard at bytethirst.app, or both. Opt-in only.

bytethirst config cloud-sync true

🌍

What syncs

Daily query counts, est. water mL, energy Wh, CO₂ g, and platform breakdown. That’s it.

🚫

What never syncs

Prompts, responses, conversation content, file paths, or any raw interaction data. Ever.

🗑️

Reversible

Turn it off and delete all cloud data at any time. Local data is never affected.

Badges

Earn badges for sustainable AI usage. 21 badges (6 free + 15 premium) that sync across devices.

bytethirst badges

💧

First Drop1+ lifetime query

📊

Half Century50+ queries

🍃

Lighter Footprint10% weekly reduction

🔥

Streak Master4 decrease weeks

⚡

Efficient Week>50% small models

👣

Footprint Aware30+ CLI sessions

Plus 15 more premium badges across reduction, streaks, efficiency, awareness, and mindful usage categories.

Developer Notes

Technical details for developers integrating ByteThirst CLI into their workflow.

📦 Architecture

The CLI wraps AI tools in a pseudo-terminal via node-pty (ConPTY on Windows). All I/O passes through unchanged — your tool’s colors, cursor movement, and line editing work exactly as without ByteThirst.

A StreamCounter strips ANSI escape codes and counts clean characters. An InteractionDetector uses adapter-provided regex patterns to detect request/response boundaries. A SessionTracker converts character counts to token estimates using the platform’s chars-per-token ratio (e.g., Claude = 3.8, ChatGPT = 4.0).

📊 Estimation Engine

Same calculation engine as the Chrome extension. Anchor: 100 input + 500 output tokens (standard tier) = 0.30 Wh. Model tier multipliers: small (0.3×), standard (1.0×), large (2.5×), reasoning (5.0×). Code-gen tools use a reduced 5× output token weight (vs 15× for text chat) per Couch 2026.

All values use the mid estimate only. Water: est. prefix, 1 decimal. Energy: ≈ prefix, 2 decimals. CO₂: ≈ prefix, 2 decimals.

🔧 Adapter System

Each CLI tool gets a ToolAdapter that declares: platform ID, code-gen flag, model detection logic, and response boundary patterns. The adapter is auto-detected from the command name (claude → claude-code).

Aider’s adapter dynamically resolves the platform from its --model flag (e.g., --model claude-3.5-sonnet maps to the claude platform). Override any adapter with --adapter <name>.

🔒 Authentication

Three methods matching the Chrome extension: Google OAuth (localhost redirect), Microsoft Entra ID (localhost redirect → Cloud Function custom token), and Email/Password (interactive terminal prompts).

Credentials stored in ~/.bytethirst/auth.json. The CLI uses firebase/auth (standard web SDK), not the web-extension build. Calls ensureUserDoc Cloud Function after sign-in.

💾 Data Storage

Local data in ~/.bytethirst/data/day_YYYY-MM-DD.json using the same DailyRecord schema as the Chrome extension’s chrome.storage.local.

Cloud sync via the syncMemberData Cloud Function — same payload format as the extension. Auto-sync runs after each exec session when authenticated. Sync requires team membership.

💻 JSON Output

All commands that display data support --json or --format json for programmatic use. Export history as CSV: bytethirst history --days 30 --format csv > impact.csv.

The calc command with --json returns the full impact estimate including low/mid/high ranges, tier multiplier, and code-gen flag.

Source & Resources

npm: npmjs.com/package/bytethirst
Node.js: 18+ required (uses ESM, node-pty ConPTY)
License: MIT
Tests: 82 passing (vitest) — calculation, formatting, adapters, stream counting, interaction detection

One Account, Every Surface

Sign in with the same account across the Chrome extension, CLI, and Teams dashboard. Browser and terminal AI usage in one place.

🌐 Chrome Extension

💻 CLI Tool

📊 Teams Dashboard

Get Started