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 (and other AI tools) write code fast. But debugging that code takes time — time that's invisible in sprint planning, productivity metrics, and AI ROI discussions.

bugclock 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 AI-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 AI-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 AI-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 AI-generated files in the repo
bugclock mark <file>             Manually tag a file as AI-generated
bugclock export                  Export data as JSON or CSV
  --format  json|csv
  --days  <N>
  -o / --output  <path>
bugclock uninstall               Remove git hooks

---

Report output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  bugclock  · last 30 days
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Total Sessions:      12
  Resolved:            10
  Abandoned:            2
  Total Time:      143.5 min
  Avg / Session:    11.9 min
  Longest:          48.2 min

  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 registry is a simple JSON file — commit it so every teammate's tracker stays in sync:

git add .claude-tracker/marked_files.json
git commit -m "chore: mark AI-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.json	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

# Python
pip install -e ".[dev]"

# Node.js
cd npm && npm install

Please open an issue first for large changes.

---

Links

• npm: https://www.npmjs.com/package/bugclock
• PyPI: https://pypi.org/project/bugclock/
• GitHub: https://github.com/adhithyakiran/bugclock

---

License

MIT — Adhithya Kiran