bugclock 0.1.0

Track debugging time spent on AI-generated code

bugclock

Track exactly how much time your team spends debugging AI-generated code.

Whether you're a solo developer or a 500-person engineering org, bugclock gives you honest data on the real cost of AI-generated code — so you can make smarter decisions about when and how to use it.

---

Why this exists

Claude writes code fast. But debugging that code takes time — time that's invisible in sprint planning, productivity metrics, and AI ROI discussions.

This tool makes that time visible.

Total debug time (last 30 days):   143.5 min
Average per session:                11.9 min
Most debugged file:  src/auth/login.py  (4 sessions, 61.5 min)

---

Install

# Python
pip install bugclock

# JavaScript / Node.js
npm install -g bugclock

Requires Python 3.8+ or Node.js 16+. Works on macOS, Linux, and Windows.

---

Quickstart (30 seconds)

# 1. Initialize in your project repo
cd your-project/
bugclock init

# 2. Mark Claude-generated files
bugclock mark src/auth/login.py
# — or add a comment anywhere in the file —
# @claude-generated

# 3. Start a debug session
bugclock start -f src/auth/login.py -n "JWT tokens not expiring"

# 4. Fix it, then stop
bugclock stop --resolved

# 5. See your analytics
bugclock report

---

How it works

Three ways to detect Claude-generated code

Method	Example
Comment marker	Add # @claude-generated to any file (any language)
Git commit message	Commits containing [claude] or generated by claude
Manual mark	bugclock mark <file> — saved to a team-committable registry

Auto-inference — zero friction tracking

After bugclock init, a silent post-commit hook runs on every commit:

1. Checks if modified files are Claude-generated
2. Looks for fix-related keywords in the commit message (fix, bug, patch, resolve…)
3. Estimates session duration from file modification timestamps
4. Auto-records the debug session — no start/stop needed

Your team gets data even when they forget to run any commands.

---

Commands

bugclock init                    Set up DB + git hooks in the current repo
bugclock start                   Begin a debug session
  -f / --file  <path>                 File(s) being debugged (repeatable)
  -n / --note  <text>                 Note about the bug
bugclock stop                    End the active session
  --resolved / --abandoned            Outcome (default: resolved)
bugclock status                  Show the active session + elapsed time
bugclock report                  Full analytics dashboard
  --days  <N>                         Time window in days (default: 30)
bugclock sessions                List recent sessions
  --limit  <N>
  --status  resolved|abandoned|active
bugclock scan                    Find all Claude-generated files in the repo
bugclock mark <file>             Manually tag a file as Claude-generated
bugclock export                  Export data as JSON or CSV
  --format  json|csv
  --days  <N>
  -o / --output  <path>
bugclock uninstall               Remove git hooks

---

Report output

╭─ Claude Debug Tracker  last 30 days ─────────────────────────╮

 ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
 │     12     │  │     10     │  │      2     │  │  143.5 min │
 │   Total    │  │  Resolved  │  │  Abandoned │  │ Total Time │
 └────────────┘  └────────────┘  └────────────┘  └────────────┘

  Daily Debug Time (minutes)
  2026-04-12   12.3  ████████░░░░░░░░░░░░
  2026-04-13    0.0  ░░░░░░░░░░░░░░░░░░░░
  2026-04-14   48.2  ████████████████████
  2026-04-15    8.5  █████░░░░░░░░░░░░░░░

  Most-Debugged Files
  src/auth/login.py        4 sessions   61.5 min
  src/api/payments.py      3 sessions   38.0 min
  src/utils/parser.py      2 sessions   22.0 min

---

Team & company usage

Share the file registry with your team

The file registry is just JSON — commit it so every teammate's tracker stays in sync:

git add .claude-tracker/marked_files.json
git commit -m "chore: mark Claude-generated files for debug tracking"

Export for dashboards

# CSV → Excel / Google Sheets / Tableau
bugclock export --format csv --days 90 -o debug_data.csv

# JSON → Grafana / internal dashboards
bugclock export --format json --days 90 -o debug_data.json

GitHub Actions — weekly team report

# .github/workflows/debug-report.yml
name: Weekly Debug Report
on:
  schedule:
    - cron: "0 9 * * MON"   # every Monday at 9am

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install bugclock
      - run: bugclock report --days 7

---

Adding the marker to your files

Any of these work — pick what fits your language:

# @claude-generated              ← Python

// @claude-generated             ← JavaScript / TypeScript

// generated by claude           ← Go

// @claude-generated             ← Rust

// @claude-generated             ← Java

-- generated by claude           ← SQL

Or use your commit message — no file changes required:

git commit -m "[claude] add user authentication flow"

---

Privacy

Data	Where it lives	Committed?
Session timings	.claude-tracker/sessions.db (SQLite)	No — gitignored
Marked file registry	.claude-tracker/marked_files.json	Optional — your choice

Nothing is ever sent to any server. The tracker is entirely local.

---

Contributing

Pull requests are welcome. To get started:

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

Please open an issue first for large changes.

---

License

MIT — Adhithya Kiran