#  TASK | Project | Description | Time Spent | Status
1. Improved report output | dev-report | Fixed report issue | 25m | Completed
2. Improved report rows | dev-report | Made rows compact | 15m | Completed
3. Polished text output | dev-report | Improved portability | 10m | Completed

Install

npm — Windows, Mac, Linux

npm install -g dev-report

The npm package automatically downloads the correct pre-built binary for your OS.

GitHub Packages is a separate registry. To install the GitHub-hosted mirror, authenticate first and then install the scoped package:

npm login --scope=@tonmoytalukder --auth-type=legacy --registry=https://npm.pkg.github.com
npm install -g @tonmoytalukder/dev-report --registry=https://npm.pkg.github.com

Homebrew — Mac only

brew tap TonmoyTalukder/homebrew-dev-report
brew install dev-report

VS Code / Open VSX Extension

Search "Dev Report" in the Extensions panel, or install from open-vsx.org.

Direct Binary

Download for your platform from GitHub Releases, unzip, and put the binary on your PATH.

Setup

This is a one-time setup. Run it once per project (or globally).

Step 1 — Run the setup wizard

Open a terminal in your project folder and run:

dev-report init

This starts an interactive wizard that asks:

• Git author name — your name as it appears in git log (e.g. TonmoyTalukder)
• GitHub username — your GitHub account name used for repo/package publishing (e.g. TonmoyTalukder)
• AI provider — which AI to use (default: groq)
• API key — for the provider you chose
• Default output format — table, markdown, excel, or json

When done, a dev-report.config.json file is created in your project.

Step 2 — Review your config

Open dev-report.config.json — it looks like this:

{
  "user": "TonmoyTalukder",
  "githubUsername": "TonmoyTalukder",
  "aiProvider": "groq",
  "groqApiKey": "gsk_...",
  "groqModel": "llama-3.3-70b-versatile",
  "geminiApiKey": "",
  "openRouterApiKey": "",
  "ollamaUrl": "http://localhost:11434",
  "ollamaModel": "llama3",
  "defaultOutput": "table"
}

Fill in only what you need. You just need the key for the provider you picked.

Step 3 — Add config to .gitignore

Your config file contains your API key. Add it to .gitignore so it never gets committed:

echo "dev-report.config.json" >> .gitignore

No one else will ever see your API key. Each developer has their own dev-report.config.json with their own key. The tool does not bundle any API keys.

Step 4 — Generate your first report

dev-report generate --hours=9h --adjust=35min

Done! ✅

API Keys

All supported AI providers offer a free tier. No credit card required.

Groq (default — fastest)

1. Go to console.groq.com → sign up (free)
2. Click API Keys → Create API Key
3. Copy the key (starts with gsk_...)
4. Paste it in dev-report.config.json:

   {
     "aiProvider": "groq",
     "groqApiKey": "gsk_your_key_here"
   }

Free models you can use: | Model | Speed | Quality | |-------|-------|---------| | llama-3.3-70b-versatile (default) | Fast | High | | llama3-8b-8192 | Very fast | Good | | gemma2-9b-it | Fast | Good |

Google Gemini

1. Go to aistudio.google.com/app/apikey → sign in with Google
2. Click Create API Key → select a project
3. Copy the key (starts with AIza...)
4. Paste it in dev-report.config.json:

   {
     "aiProvider": "gemini",
     "geminiApiKey": "AIza_your_key_here"
   }

Ollama (runs locally — no API key needed)

1. Download and install Ollama from ollama.com
2. Pull a model:

   ollama pull llama3

3. Add to dev-report.config.json:

   {
     "aiProvider": "ollama",
     "ollamaUrl": "http://localhost:11434",
     "ollamaModel": "llama3"
   }

No API key, no internet required once the model is downloaded.

OpenRouter (access to many free models)

1. Go to openrouter.ai/keys → create account
2. Click Create Key → copy it (starts with sk-or-...)
3. Paste it in dev-report.config.json:

   {
     "aiProvider": "openrouter",
     "openRouterApiKey": "sk-or-your_key_here"
   }

Free models: | Model | |-------| | meta-llama/llama-3.1-8b-instruct:free (default) | | google/gemma-3-27b-it:free | | mistralai/mistral-7b-instruct:free |

Usage

Basic commands

# Generate report for today (time range)
dev-report generate --checkin=09:00 --checkout=18:00

# Generate report for today's full commits using a total hours budget
dev-report generate --hours=9h --adjust=35min

# With break time deducted (35 min break → subtracted from task time)
dev-report generate --checkin=09:00 --checkout=18:00 --adjust=35min

# Specific date
dev-report generate --date=2026-03-07 --checkin=09:00 --checkout=17:30

# Specific date with full-day commits and a total budget
dev-report generate --date=2026-03-07 --hours=8h30m --adjust=30m

# Last N commits (no time range needed)
dev-report generate --last=10

# Filter by Git author
dev-report generate --user=TonmoyTalukder --checkin=09:00 --checkout=18:00

# Use a different AI provider for this run only
dev-report generate --checkin=09:00 --checkout=18:00 --ai=gemini

# Keep each commit as its own task with an explicit time budget
dev-report generate --hours=9h --adjust=35min --task-mode=granular

# Keep more task detail even without check-in/check-out
dev-report generate --last=20 --task-mode=granular

Output formats

# Print clean shareable text in terminal (default)
dev-report generate --hours=9h --adjust=35min

# Print as Markdown
dev-report generate --hours=9h --adjust=35min --output=markdown

# Save as Markdown file
dev-report generate --hours=9h --adjust=35min --output=markdown --out=report.md

# Export to Excel
dev-report generate --hours=9h --adjust=35min --output=excel

# Save as JSON
dev-report generate --hours=9h --adjust=35min --output=json

The default terminal output is optimized for copy-paste into chat apps like WhatsApp, Slack, and email. It uses plain numbered tasks instead of heavy ASCII table borders.

Task modes

Use --task-mode to control how aggressively commits are grouped into report tasks.

| Mode | Best for | Behavior | |------|----------|----------| | balanced | Default daily use | Natural grouping with clean, manager-friendly task rows | | detailed | Slightly more separation | Keeps more distinct work items when the evidence is clear | | granular | Maximum task detail | Preserves each commit as its own task row |

# Default balanced mode
dev-report generate --last=20

# Slightly more task separation
dev-report generate --last=20 --task-mode=detailed

# Keep each commit as a separate task
dev-report generate --last=20 --task-mode=granular

# Granular mode also works with a real time budget
dev-report generate --hours=9h --adjust=35min --task-mode=granular

All flags

| Flag | Description | Example | |------|-------------|---------| | --user | Git author name filter | --user=TonmoyTalukder | | --date | Date (default: today) | --date=2026-03-07 | | --checkin | Work start time | --checkin=09:00 | | --checkout | Work end time | --checkout=18:00 | | --hours | Total day budget across that date's commits | --hours=8h30m | | --adjust | Break time to subtract | --adjust=35min, --adjust=1h30m | | --last | Last N commits | --last=10 | | --task-mode | Task granularity mode | --task-mode=balanced, --task-mode=detailed, --task-mode=granular | | --ai | AI provider override | --ai=gemini | | --output | Output format | --output=excel | | --out | Save to file | --out=report.md |

How time is distributed

When you provide --checkin and --checkout, the tool calculates your total task time budget:

Budget = (checkout − checkin) − adjust

When you provide --hours, the tool uses that value as the total budget for the selected date's commits:

Budget = hours − adjust

Each task gets a proportional share based on:

• Commit count — tasks with more commits get more time
• Time spread — gap between first and last commit in the task
• Files changed — more files = more time
• Lines changed — larger diffs = more time
• File complexity — migrations, configs get a small boost
• Commit type — feat: > fix: > chore: as a multiplier

The sum of all time values always equals your budget exactly.

If you do not provide --checkin, --checkout, or --hours, the tool estimates a reasonable total from your work history. In detailed and granular modes, the report can show more task rows without artificially inflating the estimated total day length.

Package registries

• npmjs public package — dev-report
• GitHub Packages mirror — @tonmoytalukder/dev-report

Publishing to npmjs does not populate the GitHub repository's Packages tab. That page only shows packages published to GitHub Packages at npm.pkg.github.com.

VS Code Extension

The VS Code extension lets you generate reports without leaving your editor.

Install

Search "Dev Report" in the Extensions sidebar, or install from open-vsx.org.

Commands

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and search for:

| Command | What it does | |---------|-------------| | Dev Report: Generate Work Report | Generate with default settings | | Dev Report: Generate Work Report (with options) | Opens a panel to set options | | Dev Report: Open Dev Report Panel | Opens the sidebar panel | | Dev Report: Configure Dev Report | Opens settings |

Configure in VS Code settings

If you want one global configuration that applies to all projects, configure through VS Code instead of per-project dev-report.config.json:

1. Open VS Code Settings (Ctrl+, / Cmd+,)
2. Search for Dev Report
3. Fill in your values

Or in settings.json:

{
  "devReport.user": "TonmoyTalukder",
  "devReport.aiProvider": "groq",
  "devReport.groqApiKey": "gsk_...",
  "devReport.geminiApiKey": "",
  "devReport.openRouterApiKey": "",
  "devReport.ollamaUrl": "http://localhost:11434",
  "devReport.defaultOutput": "markdown"
}

Tip: VS Code settings apply globally across all your projects. Per-project dev-report.config.json overrides VS Code settings for that specific project.

Config Priority

Configuration is applied in this order (later overrides earlier):

VS Code settings
    ↓
dev-report.config.json  (in your project folder)
    ↓
CLI flags  (e.g. --ai=gemini)

Build from Source

git clone https://github.com/TonmoyTalukder/dev-report
cd dev-report
go build -o dev-report .

# Windows
go build -o dev-report.exe .

License

MIT