Metadata-Version: 2.4
Name: codechron
Version: 1.0.0
Summary: Zero-configuration background tool that automatically tracks developer activity and generates structured daily work logs.
Author-email: Nilen Patel <nilenp22@gmail.com>
Maintainer-email: Nilen Patel <nilenp22@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://nilenpatelinc.com
Project-URL: Repository, https://github.com/nilenpatel/codechron
Project-URL: Issues, https://github.com/nilenpatel/codechron/issues
Keywords: developer,activity,tracker,logging,git,productivity
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=3.0.0
Dynamic: license-file

# codechron

**Zero-configuration developer activity tracker.**

codechron runs silently in the background, watches your project for file changes, extracts Git diffs, groups activity into sessions, and generates structured Markdown daily logs — all with zero setup.

Developed and maintained by **Nilen Patel**, a Developer. The goal of this package is to provide a minimal, reliable, and automated system for tracking development activity without disrupting the coding process, emphasizing simplicity, performance, and usability.

---

## Features

- **Automatic file tracking** — monitors creates, modifications, and deletions using watchdog
- **Git integration** — captures lines added/removed per file via `git diff --numstat`
- **Session grouping** — clusters activity into sessions based on configurable inactivity thresholds (default: 15 minutes)
- **Structured Markdown logs** — generates daily work logs with summaries, session breakdowns, and per-event detail
- **Event debouncing** — suppresses duplicate events from autosave and IDE churn
- **SQLite storage** — lightweight, fast, local-only data persistence with WAL mode
- **Background daemon** — runs as a detached process with PID-based lifecycle management
- **Cross-platform** — works on Linux, macOS, and Windows
- **Fully offline** — no APIs, no AI, no telemetry, no network access

## Installation

```bash
pip install codechron
```

### From source

```bash
git clone https://github.com/nilenpatel/codechron.git
cd codechron
pip install .
```

### Dependencies

- Python >= 3.9
- [watchdog](https://pypi.org/project/watchdog/) >= 3.0.0
- Git (optional, for diff tracking)

## Quick Start

```bash
# Initialize codechron in your project
cd /path/to/your/project
codechron init

# Start tracking
codechron start

# Check status
codechron status

# View today's activity
codechron today

# Generate a daily log file
codechron log

# Stop tracking
codechron stop
```

## CLI Reference

```
codechron [--version] [--directory DIR] [--verbose] <command>
```

### Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize codechron in the current project directory |
| `start` | Start the background tracker |
| `start -f` | Start in the foreground (useful for debugging) |
| `stop` | Stop the running tracker |
| `status` | Show tracker status and today's summary |
| `today` | Print today's activity log to stdout |
| `log` | Generate a Markdown log file in `.codechron/logs/` |
| `log --date 2026-03-20` | Generate a log for a specific date |
| `log --stdout` | Print the log to stdout instead of writing to file |

### Global Options

| Option | Description |
|--------|-------------|
| `-d, --directory DIR` | Project directory to track (default: auto-detected) |
| `-v, --verbose` | Enable debug logging to stderr |
| `--version` | Show version and exit |

## How It Works

1. **`codechron init`** creates a `.codechron/` directory in your project root containing configuration, the SQLite database, and generated logs.

2. **`codechron start`** launches a background daemon that:
   - Watches all files recursively using watchdog
   - Filters out ignored paths (`.git`, `__pycache__`, `node_modules`, hidden files, binary extensions)
   - Debounces rapid-fire events (default: 2 seconds)
   - Extracts Git diff stats for modified files
   - Groups events into sessions based on inactivity (default: 15 minutes)
   - Stores everything in a local SQLite database

3. **`codechron log`** reads from the database and generates a structured Markdown report for the requested day.

## Configuration

Configuration is stored in `.codechron/config.json` and can be edited directly:

```json
{
  "debounce_seconds": 2.0,
  "session_timeout_minutes": 15,
  "ignore_patterns": [
    ".git", "__pycache__", "node_modules", ".venv",
    "venv", "env", ".env", ".tox", ".mypy_cache",
    ".pytest_cache", ".ruff_cache", "dist", "build",
    "*.egg-info", ".codechron"
  ],
  "ignore_extensions": [
    ".pyc", ".pyo", ".o", ".so", ".dylib", ".dll",
    ".class", ".exe", ".bin", ".lock", ".log",
    ".db", ".db-journal", ".sqlite", ".sqlite-journal"
  ],
  "ignore_hidden": true,
  "verbose": false
}
```

## Project Structure

```
codechron/
├── __init__.py          # Package metadata
├── __main__.py          # python -m codechron entry point
├── cli.py               # CLI argument parsing and command handlers
├── config.py            # Configuration management
├── daemon.py            # Background process lifecycle
├── git_integration.py   # Git diff extraction
├── log_generator.py     # Markdown report generation
├── session.py           # Session grouping engine
├── storage.py           # SQLite database layer
├── utils.py             # Shared utilities
└── py.typed             # PEP 561 marker
```

## Example Output

See [`examples/2026-03-26.md`](examples/2026-03-26.md) for a sample daily log.

## Data Storage

All data is stored locally in `.codechron/`:

```
.codechron/
├── config.json       # User configuration
├── codechron.db      # SQLite database (WAL mode)
├── codechron.pid     # Background process PID
└── logs/
    └── 2026-03-26.md # Generated daily logs
```

Add `.codechron/` to your `.gitignore` — `codechron init` does this automatically.

## License

[MIT](LICENSE) — Nilen Patel
