____             ____        __
|  _ \  _____   _|  _ \ _   _\ \ ___ ___  ___
| | | |/ _ \ \ / / |_) | | | \ \/ __/ _ \/ __|
| |_| |  __/\ V /|  __/| |_| |> > (_|  __/\__ \
|____/ \___| \_/ |_|    \__,_/_/ \___\___||___/

DevPulse

Developer productivity CLI — track coding time, analyze Git activity, generate reports.

DevPulse is a lightweight, zero-dependency* CLI tool that helps individual developers understand how they spend their coding time. It combines manual time tracking with automatic Git analysis to produce clear daily and weekly reports.

*One runtime dependency: commander.

• ⏱️ Time Tracking — start/stop sessions, tag projects, manual entries
• 📊 Git Analysis — commits, files changed, insertions/deletions per day
• 📋 Reports — daily and weekly summaries combining time + Git data

Installation

npm install -g @for7candy/devpulse

Requires Node.js ≥ 18 and Git (for Git analysis features).

Quick Start

# Start tracking a coding session
devpulse track start my-project -t coding,typescript

# Check current status
devpulse track status

# Stop the session
devpulse track stop

# View session history
devpulse track log

# Generate today's report
devpulse report daily

That's it. Data is stored locally at ~/.devpulse/ — nothing leaves your machine.

Command Reference

devpulse track

| Command | Description | Options | |---------|-------------|---------| | track start [project] | Start a new tracking session | -t, --tags <tags> comma-separated | | track stop | Stop the current session | — | | track status | Show active session and elapsed time | — | | track log | List completed sessions | -d, --date <YYYY-MM-DD> -p, --project <name> --json | | track add <minutes> | Manually record a session | -p, --project <name> -d, --date <YYYY-MM-DD> |

Cross-day sessions are automatically split at midnight when you stop — no lost data.

devpulse report

| Command | Description | Options | |---------|-------------|---------| | report daily | Generate a daily report | -d, --date <YYYY-MM-DD> -f text\|json -o, --output <file> | | report weekly | Generate a weekly report | -w, --week-start <YYYY-MM-DD> -f text\|json -o, --output <file> |

Example output:

═══════════════════════════════════
  Daily Report — 2026-06-24
═══════════════════════════════════

  Coding time: 150 minutes
  Sessions:    2
  Git commits: 5

  On 2026-06-24, coding time was 2h 30m across 2 sessions. Git: 5 commits, 12 files changed.

devpulse config

| Command | Description | |---------|-------------| | config show | Display current configuration | | config set <key> <value> | Set a configuration value | | config init | Initialize config with defaults | | config path | Print config file location |

Configuration

Config file: ~/.devpulse/config.json

| Key | Type | Default | Description | |-----|------|---------|-------------| | dataDir | string | ~/.devpulse | Data storage directory | | gitRepoPath | string \| null | null | Git repo path (null = auto-detect cwd) | | defaultProject | string \| null | null | Default project for track start | | reportFormat | 'text' \| 'json' | 'text' | Default report output format | | workHoursStart | string \| null | null | Work hours filter start ("HH:mm") | | workHoursEnd | string \| null | null | Work hours filter end ("HH:mm") |

# Examples
devpulse config set reportFormat json
devpulse config set defaultProject devpulse
devpulse config show

Development

# Clone and install
git clone https://github.com/For7candy/devpulse.git
cd devpulse
npm install

# Compile
npx tsc
# or: npm run build

# Run tests
npm test                  # 62 tests, 5 suites
npm run test:coverage     # > 80% coverage

# Run locally
node dist/index.js --help

Project Structure

src/
├── index.ts              # CLI entry point
├── commands/             # Commander.js subcommands
│   ├── track.command.ts
│   ├── report.command.ts
│   └── config.command.ts
├── lib/                  # Business logic
│   ├── result.ts         # Result<T, E> pattern
│   ├── time-tracker.ts
│   ├── git-analyzer.ts
│   ├── report-generator.ts
│   └── config-manager.ts
├── storage/              # JSON persistence layer
│   ├── storage-service.ts
│   ├── tracking-store.ts
│   └── config-store.ts
└── types/                # TypeScript interfaces
    ├── tracking.ts
    ├── git.ts
    ├── report.ts
    └── config.ts

Tech Stack

• Runtime: Node.js ≥ 18
• Language: TypeScript (strict mode, ES2022, CommonJS)
• CLI Framework: Commander.js
• Testing: Jest + ts-jest
• Storage: Local JSON files with atomic writes

License

MIT © 2026 For7candy