PTC - Punch the Clock

A task-based time tracking CLI tool designed for developers and AI coding agents to measure development velocity.

Overview

PTC (Punch the Clock) allows you to create projects, attach tasks with numbers, titles, descriptions, states, and tags, then track time using simple start/pause/resume/stop commands. All time calculations are based on timestamps - no actual timers required. Perfect for measuring development velocity and estimation accuracy.

Features

• ✅ Project Management: Create, list, and switch between projects
• ✅ Task Management: Add, update, and track tasks with metadata
• ✅ Time Tracking: Start, pause, resume, and stop time tracking sessions
• ✅ Estimation Tracking: Track size and time estimates for velocity analysis
• ✅ Reporting: Generate time, velocity, and estimation accuracy reports
• ✅ Database Integration: MySQL database with connection pooling
• ✅ Performance: Optimized for large datasets (1000+ tasks)
• ✅ CLI Interface: Simple, intuitive command-line interface
• ✅ Error Handling: Comprehensive error handling with user-friendly messages
• ✅ Configuration: Flexible configuration management

Installation

npm install -g punch-the-clock

Prerequisites

• Node.js 16.0.0 or higher
• MySQL 8.0 or higher (local or remote)

Quick Start

# Initialize a new project
ptc init my-project

# Add a task with optional estimates
ptc add "Fix login bug" --estimate 2h --size 3

# Start tracking time
ptc start 1

# Pause, resume, or stop
ptc pause
ptc resume
ptc stop

# Generate velocity reports
ptc report velocity
ptc report estimates

Commands

Project Management

ptc init <project-name>          # Create a new project
ptc list projects                # List all projects
ptc project <project-name>       # Switch to a project

Task Management

ptc add <title>                  # Add a new task
ptc list tasks                   # List tasks in current project
ptc task <task-id>               # Show task details
ptc update <task-id>             # Update task properties

Time Tracking

ptc start <task-id>              # Start time tracking
ptc pause                        # Pause current tracking
ptc resume                       # Resume paused tracking
ptc stop                         # Stop time tracking

Reporting

ptc report time                  # Show time tracking reports
ptc report velocity              # Show velocity metrics
ptc report estimates             # Show estimation accuracy

Configuration

ptc config show                  # Show current configuration
ptc config set <key> <value>     # Set configuration value

Database Setup

PTC will automatically create the database schema on first run. You can also set it up manually:

# Create database
mysql -u root -p -e "CREATE DATABASE ptc;"

# Set up user (optional)
mysql -u root -p -e "CREATE USER 'ptc'@'localhost' IDENTIFIED BY 'password';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON ptc.* TO 'ptc'@'localhost';"

Configuration

Create a .ptcrc file in your home directory:

{
  "database": {
    "host": "localhost",
    "port": 3306,
    "user": "ptc",
    "password": "password",
    "database": "ptc"
  }
}

Performance

• CLI commands respond within 100ms
• Optimized for large datasets (1000+ tasks)
• Memory usage optimized
• Concurrent operation support
• Performance monitoring and metrics

Development

# Clone the repository
git clone https://github.com/ptc-team/punch-the-clock.git
cd punch-the-clock

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

Changelog

See CHANGELOG.md for a list of changes and version history.