ptracker

A CLI tool for tracking projects, file activity, and hours for freelancers.

Features

• init — initialize a new project with global storage in ~/.ptracker
• watch — real-time file system monitoring with automatic session tracking
• log — manually log hours to a project
• summary — view project details, hours, and today's session activity
• list — show all projects across your machine in a table
• sessions — view all sessions for a project with full breakdown
• export — generate a client-facing project report
• rename — rename a project globally
• delete — remove a project and all its data
• clean — compress old logs to free up space
• repair — recover orphaned projects back into the registry

Latest Version
Crate Downloads
License

Table of Contents

• Installation
• Usage
• TUI Dashboard
• How it works
• Data
• Release History
• Authors
• License

Installation

cargo install ptracker

Usage

# Initialize a new project
ptracker init "My Project"

# Initialize with a specific folder to watch
ptracker init "My Project" --path ./src

# Watch a folder and track file activity
ptracker watch "My Project"

# Watch a specific folder for this session
ptracker watch "My Project" --path ./src

# Log hours manually
ptracker log "My Project" 3.5

# View project summary with session breakdown
ptracker summary "My Project"

# List all projects
ptracker list

# View all sessions for a project
ptracker sessions "My Project"

# View sessions for a specific date
ptracker sessions "My Project" --date 2026-06-28

# Export a client report
ptracker export "My Project"

# Export to a specific file
ptracker export "My Project" --output client-report.txt

# Rename a project
ptracker rename "My Project" "New Name"

# Delete a project
ptracker delete "My Project"

# Compress old logs
ptracker clean "My Project"

# Recover orphaned projects
ptracker repair

# Show version
ptracker --version

TUI Dashboard

Run ptracker with no arguments to launch the interactive dashboard:

ptracker

Key	Action
↑ / k	Navigate up
↓ / j	Navigate down
Enter	View sessions for selected project
w	Start watching selected project
e	Export report for selected project
q / Esc	Quit

How it works

ptracker watches your project folders in real time, logging every file creation, modification, rename, and deletion. Each work session is automatically timed — start with watch, stop with Ctrl+C, and ptracker saves the session duration, file event totals, and activity log automatically.

Old log files are compressed to .log.gz automatically at the start of each new session to keep your storage footprint small.

All data lives in ~/.ptracker so your projects are accessible from any terminal on your machine.

Data

All project data is stored globally in your home directory:

~/.ptracker/
├── projects.json               # global project registry
└── projects/
    └── my-project/
        ├── project.json        # project metadata and totals
        ├── sessions/
        │   └── 2026-06-28.json # per-day session file
        └── logs/
            ├── 2026-06-28.log  # today's activity log
            └── 2026-06-27.log.gz # compressed old log

Release History

See the changelog for a full release history.

Authors

Created and maintained by Precious Adeyinka.

License

Licensed under the MIT license — see LICENSE for details.