Metadata-Version: 2.4
Name: bugclock
Version: 0.1.0
Summary: Track debugging time spent on AI-generated code
License: MIT
Project-URL: Homepage, https://github.com/adhithyakiran/bugclock
Project-URL: Issues, https://github.com/adhithyakiran/bugclock/issues
Keywords: bugclock,ai,debugging,productivity,developer-tools,claude
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Dynamic: license-file

# bugclock

[![PyPI version](https://img.shields.io/pypi/v/bugclock)](https://pypi.org/project/bugclock/)
[![npm version](https://img.shields.io/npm/v/bugclock)](https://www.npmjs.com/package/bugclock)
[![Python](https://img.shields.io/pypi/pyversions/bugclock)](https://pypi.org/project/bugclock/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/bugclock)](https://pypi.org/project/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

```bash
# 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)

```bash
# 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:

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

### Export for dashboards

```bash
# 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

```yaml
# .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:

```python
# @claude-generated              ← Python
```
```javascript
// @claude-generated             ← JavaScript / TypeScript
```
```go
// generated by claude           ← Go
```
```rust
// @claude-generated             ← Rust
```
```java
// @claude-generated             ← Java
```
```sql
-- generated by claude           ← SQL
```

Or use your commit message — no file changes required:
```bash
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:

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

Please open an issue first for large changes.

---

## License

[MIT](LICENSE) — Adhithya Kiran
