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

pip install codechron

From source

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

Dependencies

• Python >= 3.9
• watchdog >= 3.0.0
• Git (optional, for diff tracking)

Quick Start

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

{
  "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 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 — Nilen Patel