Skip to main content

VoidTally logo

VoidTally

A non-intrusive performance observation tool for AI CLI developers. VoidTally quantifies "The Void" - the time wasted waiting between user input and AI response.

Features

  • 🎯 Zero-Impact Monitoring: PTY proxy with 100% ANSI passthrough
  • ⏱️ Precise Timing: Measures TTLT (Time to Last Token) — from Enter (submit) to the last AI output character
  • 📊 Rich TUI Dashboard: Statistics, 7-day trends, and file details
  • 📧 Email Reports: Automated daily void time reports with HTML formatting
  • 📸 Snapshot Attribution: Accurate LOC tracking even without Git
  • 🔍 Smart Filtering: Filter by tool and project for targeted analysis
  • 🔒 Privacy First: All data stored locally, no cloud uploads

Quick Start

Installation

# Clone the repository
git clone https://github.com/Fzzzhan/void-tally.git
cd void-tally

# Install with pip (editable mode for development)
pip install -e .

# Or install from PyPI
pip install voidtally

Requirements:

  • Python 3.7+
  • rich>=10.0.0 (auto-installed)

Basic Usage

# Monitor AI CLI tool
voidtally run aider
voidtally run claude

# GitHub Copilot CLI (standalone snap binary)
voidtally run copilot

# GitHub Copilot via gh extension (if using gh copilot)
voidtally run gh copilot suggest
voidtally run gh copilot explain

# View dashboard
voidtally board

# Filter by tool
voidtally board --tool aider
voidtally board --tool copilot      # GitHub Copilot (snap binary)
voidtally board --tool gh-copilot   # GitHub Copilot (gh extension)

# Filter by project
voidtally board --project .
voidtally board --project /path/to/project

# List tracked tools and projects
voidtally tools
voidtally projects

# Clear all data (with backup)
voidtally clear

# Email notifications
voidtally config email    # Configure email settings
voidtally send-report     # Send daily report now
voidtally schedule        # Set up automatic daily reports

Dashboard Features

The TUI dashboard displays:

  • 📊 Overall Statistics: Total sessions, void time, LOC changed, efficiency
  • 📈 7-Day Void Time Trend: ASCII bar chart showing daily wait time patterns
  • 📅 Today's Activity: Current day sessions, LOC, and attribution methods
  • 📋 Recent Sessions: Last 10 sessions with tool, void time, and file changes
  • 📄 File Details: Per-file LOC statistics from latest session

All panels support filtering by --tool and --project for targeted analysis.

Email Notifications

VoidTally can send automated daily email reports with your void time statistics.

Setup

1. Configure Email Settings

voidtally config email

You'll be prompted to enter:

  • Recipient email address
  • SMTP server (e.g., smtp.gmail.com for Gmail)
  • SMTP port (default: 587)
  • SMTP username and password
  • Daily send time (default: 20:00)

Note for Gmail users: Use an App Password instead of your regular password.

2. Test the Configuration

voidtally send-report

This sends today's report immediately to verify your settings.

3. Enable Automatic Daily Reports

voidtally schedule

This will:

  • Linux/macOS: Show instructions to add a cron job
  • Windows: Show instructions to create a Task Scheduler task

Email Report Contents

Each daily report includes:

  • ⏱️ Total void time (formatted as hours/minutes/seconds)
  • 📊 Number of sessions
  • 📝 LOC added/deleted/net change
  • 📋 Individual session details with timestamps

Reports are sent as HTML emails with color-coded statistics and session breakdowns.

For detailed setup instructions, see EMAIL_NOTIFICATION.md.

How It Works

VoidTally uses PTY (pseudo-terminal) proxy technology to transparently monitor AI CLI tools:

  1. PTY Proxy: Creates pseudo-terminal to intercept stdin/stdout without modifying the target CLI
  2. Void Observer: Measures void time as TTLT — from Enter (submit request) to the last AI output character. The measurement is finalized when the user starts typing again, or automatically after the AI goes idle.
  3. Auto-finalize: If AI output stops for 5 seconds with no further tokens, void time is recorded and the state resets. If no AI token arrives within 5 minutes of pressing Enter (e.g. session left open overnight), the interaction is discarded to prevent inflated measurements.
  4. Snapshot System: Takes before/after snapshots of source files to calculate exact LOC changes
  5. Attribution Methods:
    • 📸 Snapshot (accurate): Uses file snapshots - works without Git
    • 🔀 Git (fallback): Uses git diff when available
    • ❓ Unknown: Legacy data without attribution

Architecture

  • PTY Proxy: Zero-impact I/O forwarding with full ANSI support
  • State Machine: Precise timing with <1ms error
  • Snapshot Manager: File-based diff calculation without Git dependency
  • Local Storage: JSONL format (~500 bytes per session)
  • Privacy First: No cloud uploads, 100% local processing

Supported AI CLI Tools

  • ✅ Aider — voidtally run aider
  • ✅ Claude CLI — voidtally run claude
  • ✅ GitHub Copilot CLI — voidtally run copilot (snap binary, stored as copilot) or voidtally run gh copilot suggest / voidtally run gh copilot explain (gh extension, stored as gh-copilot)
  • ✅ Codex CLI — voidtally run codex
  • ✅ Any AI CLI — VoidTally works with all terminal-based tools

Note on GitHub Copilot: The standalone snap binary (copilot) is stored directly as copilot. If you use the gh extension instead (gh copilot …), VoidTally automatically maps it to gh-copilot so it isn't filtered out as a generic gh command. Use voidtally board --tool copilot or --tool gh-copilot depending on how you invoke it.

Troubleshooting

Dashboard colors not showing:

pip install rich>=10.0.0

No LOC statistics:

  • Files are tracked automatically via snapshot system
  • Works in both Git and non-Git directories
  • Check that files were actually modified during session

Data Format

All sessions stored in ~/.voidtally/data.jsonl:

{
  "timestamp": "2026-05-10T14:30:00Z",
  "tool": "aider",
  "void_duration_ms": 1250,
  "loc_added": 45,
  "loc_deleted": 12,
  "project_path": "/home/user/project",
  "void_count": 3,
  "changed_files": ["src/main.py"],
  "file_changes": [
    {
      "path": "src/main.py",
      "loc_added": 30,
      "loc_deleted": 8,
      "loc_net": 22
    }
  ],
  "attribution_method": "snapshot",
  "session_id": "aider_2026-05-10T14:30:00"
}

Filtering

VoidTally supports flexible filtering for targeted analysis:

# By tool
voidtally board --tool aider
voidtally board --tool claude
voidtally board --tool copilot      # GitHub Copilot (snap binary)
voidtally board --tool gh-copilot   # GitHub Copilot (gh extension)

# By project (all formats work)
voidtally board --project .
voidtally board --project ./
voidtally board --project /absolute/path

# Combined
voidtally board --tool aider --project .

Path normalization: VoidTally automatically converts relative paths (., ./) to absolute paths for consistent matching.

Tool name mapping: Some CLI tools use a wrapper command. VoidTally maps these automatically so they appear as meaningful AI tool names on the dashboard:

Command Stored as
copilot … copilot
gh copilot … gh-copilot
aider … aider
claude … claude

Performance

  • Timing Precision: < 1ms error
  • Memory Overhead: Minimal (state machine + snapshots)
  • CPU Overhead: Negligible (passive monitoring)
  • Storage: ~500 bytes per session

License

MIT


VoidTally - Stop losing time in The Void. Start tracking your AI efficiency today! 🚀

Metadata

Release files for voidtally 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for voidtally 0.2.0
File Size Uploaded Provenance Actions
voidtally-0.2.0.tar.gz 47.0 kB Without provenance Details for voidtally-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for voidtally 0.2.0
File Interpreter ABI Platform Actions
voidtally-0.2.0-py3-none-any.whl Python 3 none any Details for voidtally-0.2.0-py3-none-any.whl

Total release size: 89.3 kB

Release files / voidtally-0.2.0.tar.gz

Download URL voidtally-0.2.0.tar.gz
Size 47.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a169ecfa36d8f57478bb078ab19ea364d46a8bdaaf1cddf90b1b3a9f892bf8ac
BLAKE2b-256 checksum
How to use checksums
c55382457e35c15952ffc82972fda3fde81dc49ced4e5761da687bc2c91b6836
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Release files / voidtally-0.2.0-py3-none-any.whl

Download URL voidtally-0.2.0-py3-none-any.whl
Size 42.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7473ca91a15db8130cf7e45636eae31021a3412cc8f3f61863f6694b4cc76379
BLAKE2b-256 checksum
How to use checksums
926cf6701ae808fc769711ec6c4c0ec4cc16e188c42057aece2702a9565da9c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.12

Security for voidtally 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page