DevTrack — Developer Productivity Tracker

DevTrack is a lightweight command‑line tool to help you run focused work sessions. Start a session when you sit down to work, create and complete todos inside that session, and optionally time tasks with human‑friendly durations (e.g., 20m, 1h30m).

Unlike general todo apps, DevTrack is session‑centric: todos belong to the active session and should be completed before you stop the session, capturing a clean snapshot of what you achieved.

Table of Contents

• Overview
• Requirements
• Installation (copy‑paste ready)
  • macOS (pipx + Homebrew)
  • Linux (pipx)
  • Alternative: Virtual environment + pip (macOS/Linux)
• Quick Start (Manual Completion workflow)
• Usage Reference (Commands)
  • Sessions
  • Session Todos
  • Tasks and Duration Formats
• Data Storage and Reset
• Troubleshooting (macOS & Linux)
• Development (editable install)
• Roadmap
• License

---

Overview

• Session‑centric workflow
  • Start/stop a work session
  • Create/list/complete todos within the active session
  • Start/stop task timers associated with those todos
• Human‑friendly durations: 45s, 20m, 2h, 1h30m, or a bare 20 (minutes)
• Persistence
  • Sessions (and their todos/tasks) are stored in sessions.json in your current directory
  • A simple historical/global todo store is also kept at ~/.devtrack/todo.json
• No external dependencies; pure Python (3.11+)

Requirements

• Python 3.11 or newer on your system PATH
• A terminal (bash/zsh/fish on macOS or Linux)
• Write access to the current directory (for sessions.json) and your home directory (for ~/.devtrack/todo.json)

Installation (copy‑paste ready)

macOS (pipx + Homebrew)

Recommended for CLI tools. Paste these commands in Terminal.

# 1) Install pipx and add its bin dir to PATH
brew install pipx
pipx ensurepath
# Re‑load your shell PATH (pick the one you use)
# zsh (default on recent macOS):
source ~/.zshrc 2>/dev/null || true
# or bash:
source ~/.bashrc 2>/dev/null || true

# 2) Ensure Python 3.11+
python3 --version
# If needed:
brew install python@3.11

# 3) Install DevTrack from GitHub
pipx install git+https://github.com/ArsalanAnwer0/devtrack.git

# 4) If command not found, ensure ~/.local/bin is on PATH (rare on macOS)
export PATH="$HOME/.local/bin:$PATH"

# 5) Verify
which devtrack || true
devtrack --help

Uninstall (pipx):

pipx uninstall devtrack

Linux (pipx)

Paste these commands on Debian/Ubuntu (similar on other distros; adjust package manager accordingly).

# 1) Install pipx and add its bin dir to PATH
sudo apt-get update && sudo apt-get install -y pipx
pipx ensurepath
# Re‑load your shell PATH for this session
source ~/.bashrc 2>/dev/null || source ~/.profile 2>/dev/null || true

# 2) Ensure Python 3.11+
python3 --version

# 3) Install DevTrack from GitHub
pipx install git+https://github.com/ArsalanAnwer0/devtrack.git

# 4) If command not found, add pipx bin dir to PATH for this session and persist
export PATH="$HOME/.local/bin:$PATH"
# Persist for future shells
printf '\n# pipx apps on PATH\nexport PATH="$HOME/.local/bin:$PATH"\n' >> ~/.bashrc
printf '\n# pipx apps on PATH\nexport PATH="$HOME/.local/bin:$PATH"\n' >> ~/.profile
source ~/.bashrc

# 5) Verify
which devtrack || true
devtrack --help

Uninstall (pipx):

pipx uninstall devtrack

Alternative: Virtual environment + pip (macOS/Linux)

Use this if you prefer a project‑local install or are developing.

# 1) Create a virtual environment
python3 -m venv .venv
# macOS bash/zsh:    source .venv/bin/activate
# macOS fish shell:  source .venv/bin/activate.fish
# Linux bash/zsh:    source .venv/bin/activate

# 2) Install DevTrack (choose one)
# From the current repo clone (editable dev install):
python -m pip install -e .
# OR directly from GitHub:
python -m pip install git+https://github.com/ArsalanAnwer0/devtrack.git

# 3) Run
devtrack --help

# 4) Deactivate when done
deactivate

Quick Start (Manual Completion workflow)

The default flow expects you to explicitly complete each todo. Example session:

devtrack session start "My focused session"

# Todo #1
devtrack todo add "Implement API"
devtrack task start "Implement API" 20m
# ...do work...
devtrack task stop
devtrack todo complete 1

# Todo #2
devtrack todo add "Write tests"
devtrack task start "Write tests" 1h
# ...do work...
devtrack task stop
devtrack todo complete 2

# Review and wrap up
devtrack todo list
devtrack session stop
devtrack session list

Tip: Complete todos before you stop the session to keep that session’s record consistent.

Usage Reference (Commands)

Sessions

• Start: devtrack session start [message]
• Stop: devtrack session stop
• List: devtrack session list

Notes:

• Only one active session at a time.
• Todos and tasks created during an active session are scoped to that session.

Session Todos (require an active session)

• Add: devtrack todo add "Title"
• List: devtrack todo list
• Complete: devtrack todo complete <id>
• Delete: devtrack todo delete <id>

Notes:

• IDs are allocated by a simple global store; they are unique across sessions but you operate on the active session’s set.
• After completing a todo, devtrack todo list reflects the status immediately.

Tasks (timers linked to session todos)

• Start a task: devtrack task start "Title" <duration>
  • Duration examples (case‑insensitive, spaces allowed):
    • 45s, 20m, 2h, 1h30m, 45m30s, or a bare 20 (minutes)
• Stop the active task: devtrack task stop

Notes:

• Starting a task sets the linked todo status to in progress.
• In Manual Completion mode, stopping a task does not complete the todo; run devtrack todo complete <id> when done.

Data Storage and Reset

• sessions.json — stored in your current working directory; contains each session with its session‑scoped todos and tasks.
• ~/.devtrack/todo.json — a simple global todo store used for ID assignment and basic history.

Reset for a clean run:

rm -f sessions.json
rm -f ~/.devtrack/todo.json

Troubleshooting (macOS & Linux)

• Command not found (devtrack):
  • If using pipx, ensure PATH is configured: pipx ensurepath and restart your terminal, or source ~/.bashrc.
  • If using venv, ensure it is activated (source .venv/bin/activate[.fish]).
  • Add for current session and persist:
    • export PATH="$HOME/.local/bin:$PATH"
    • printf '\n# pipx apps on PATH\nexport PATH="$HOME/.local/bin:$PATH"\n' >> ~/.bashrc && source ~/.bashrc
• Python version errors:
  • python3 --version should be 3.11+.
  • On macOS: brew install python@3.11 then use /opt/homebrew/opt/python@3.11/bin/python3.11.
  • On Linux, install python3.11 via your package manager or use pyenv.
• Permission errors writing sessions.json or ~/.devtrack/todo.json:
  • Ensure you have write permissions to the current directory and your home directory.
• Unicode glyphs (✓, ●) look odd:
  • Change your terminal font or ignore; output remains readable.

Development (editable install)

python3 -m venv .venv
source .venv/bin/activate  # or activate.fish / Activate.ps1
python -m pip install -e .

# Run locally
devtrack --help

Project layout:

cli/
  main.py       # entrypoint (exposed as `devtrack`)
  commands.py   # CLI command handlers
core/
  manager.py       # session/todo/task orchestration
  session.py       # WorkSession model (stores session-scoped todos/tasks)
  task.py          # Task model (timers)
  todo.py          # Todo model
  todo_storage.py  # JSON-backed todo store (IDs/history)
  storage.py       # sessions.json persistence
  utils.py         # duration parsing, formatting helpers

Run tests (manual):

• Start a session; add todos; start/stop tasks using the examples above; verify sessions.json and ~/.devtrack/todo.json as needed.

Roadmap

• Optional configuration to toggle auto‑complete on task stop (vs manual completion)
• Session summary command (durations vs expected, completed/remaining todos)
• Prevent stopping a session with incomplete todos unless --force is provided
• Per‑session local IDs to reduce cross‑session ID confusion

License

Specify your license here (e.g., MIT). Add a LICENSE file if needed.