Skip to content

README.md

Latest commit

 

History

History
318 lines (234 loc) · 11.4 KB

README.md

File metadata and controls

318 lines (234 loc) · 11.4 KB
Raw

devreport

Go License: MIT

DevReport is a command-line tool that generates automated individual activity reports from ClickUp tasks. It pulls tasks, computes stats (total, completed, by status/source/type), and renders beautiful HTML/PDF reports with summaries and detailed tables.

Features

  • One-command reports: Fetch from GitHub/ClickUp → Generate HTML/PDF + JSON export
  • Smart stats: Auto-calculates totals, completion rates, breakdowns by status/source/type
  • Cross-platform: Pre-built binaries for macOS, Linux, Windows (AMD64/ARM64)
  • Optional AI Rephrasing: Integrates with Ollama for task rewording

Prerequisites

  • GitHub Account: Personal access token for API access (optional, for private repos)
  • ClickUp Account: Access to tasks via API
  • Terminal: sh/Zsh/PowerShell
  • Optional: Browser to view HTML reports
  • Optional: Ollama running locally (port 11434) for AI rephrasing

Installing Ollama and Gemma3 on linux

  1. Install Ollama:

    curl -fsSL https://ollama.com/install.sh | sh

  2. Start Ollama:

    ollama serve

  3. Pull the Gemma3 model:

    ollama pull gemma3

  4. Verify installation:

    curl http://localhost:11434/api/tags

Installation

Option 1: Download Pre-built Binary (Recommended)

  1. Go to the Releases page

  2. Download the archive for your platform:

    • macOS Intel: devreport_darwin_amd64.tar.gz
    • macOS Apple Silicon: devreport_darwin_arm64.tar.gz
    • Linux AMD64: devreport_linux_amd64.tar.gz
    • Linux ARM64: devreport_linux_arm64.tar.gz
    • Windows: devreport_windows_amd64.zip

  3. Extract and install (macOS/Linux):

    tar -xzf devreport_darwin_amd64.tar.gz
chmod +x devreport
sudo mv devreport /usr/local/bin/

  4. Verify installation:

    devreport --help

Option 2: Build from Source

git clone https://github.com/Afrawles/devreport.git
cd devreport
go build -o devreport ./cmd/devreport
./devreport --help

Getting Your ClickUp API Token

  1. Log in to ClickUp
  2. Click your profile picture → Settings
  3. Go to Apps → API Token
  4. Click Generate and copy your token
  5. Use it with the --clickup-token flag

Finding Your ClickUp List IDs

  1. In the ClickUp sidebar, hover over a List

  2. Click the ellipsis (...) → Copy link

  3. Example:

    https://app.clickup.com/12345678/v/li/987654321

  4. The number after /li/ is your List ID (987654321)

  5. Use commas to separate multiple lists:

    987654321,123456789

Finding Your ClickUp Assignee IDs

curl -H "Authorization: YOUR_API_TOKEN" \
  "https://api.clickup.com/api/v2/team"

Getting Your GitHub Personal Access Token

  1. Log in to GitHub
  2. Click your profile picture → Settings
  3. Go to Developer settings → Personal access tokens → Tokens (classic)
  4. Click Generate new token (classic)
  5. Select scopes: repo (for private repos), read:org (for org repos)
  6. Copy the token and use it with the --github-token flag

Finding Your GitHub Organizations

To fetch activities from organization repositories, specify org names (e.g., "microsoft,google").

Note: DevReport fetches from repos where you have recent activities in the date range to limit API calls.

Usage

When working with multiple ClickUp lists, DevReport maps text by list order.

  • Use commas (,) to separate different lists
  • Use pipes (|) within each list group to separate sentences belonging to that list

Example Layout

--clickup-listid "11111111,33333333" \
--challenges "Delayed client feedback|Unclear UI specifications|Integration issues with payment service, Server maintenance downtime|Third-party API instability|Deployment delays" \
--support-required "Product team review|QA support for test coverage|DevOps for CI/CD automation, Management alignment|Database admin support|Load testing assistance" \
--support-from "Product Management|QA Department|DevOps Team, IT Infrastructure|Backend Team|Project Management Office" \
--follow-up "Conduct sprint retrospective|Optimize frontend performance|Write integration tests, Refactor legacy modules|Enhance documentation|Evaluate monitoring tools"

Explanation:

  • Everything before the first comma (,) belongs to List 11111111
  • Everything after the comma belongs to List 33333333
  • Within each group, | separates sentences for that list
  • The text goes on the first row of that list's project section (not on every row)
  • For GitHub, groups follow the order of --github-repos (after any ClickUp lists); without --github-repos (or with --clickup-folderid) projects are taken alphabetically, as they appear in the report. The run prints the order it used.
  • You can also name the project instead of relying on order: --challenges "Smart Parking=Delayed client feedback|Unclear UI specifications, pidmis-backend=Deployment delays"
  • Challenges are not generated for GitHub or ClickUp activities; they only come from these flags. (The docs command below does suggest them from commits.)

Basic Command (ClickUp)

./devreport \
  --user "Uzumaki.Gon" \
  --start "2025-10-01" \
  --end "2025-10-31" \
  --author "Killua Uzumaki" \
  --period "Month of October" \
  --year 2025 \
  --category "Improvements, New Features, and Bug Fixes" \
  --clickup-token "your_clickup_token_here" \
  --clickup-assignees 1234536,1728383 \
  --clickup-listid "11111111,33333333" \
  --challenges "Delayed client feedback|Unclear UI specifications|Integration issues with payment service, Server maintenance downtime|Third-party API instability|Deployment delays" \
  --support-required "Product team review|QA support for test coverage|DevOps for CI/CD automation, Management alignment|Database admin support|Load testing assistance" \
  --support-from "Product Management|QA Department|DevOps Team, IT Infrastructure|Backend Team|Project Management Office" \
  --follow-up "Conduct sprint retrospective|Optimize frontend performance|Write integration tests, Refactor legacy modules|Enhance documentation|Evaluate monitoring tools"

GitHub Command

./devreport \
  --user "gon" \
  --start "2025-10-01" \
  --end "2025-10-31" \
  --author "Gon Freecss" \
  --period "Month of October" \
  --year 2025 \
  --github-token "your_github_token_here" \
  --github-orgs "hunterxhunter,chimera-ant" \
  --github-include-reviewed-prs \
  --github-include-assigned-issues

Combined Command (GitHub + ClickUp)

./devreport \
  --user "gon" \
  --start "2025-10-01" \
  --end "2025-10-31" \
  --author "Gon Freecss" \
  --period "Month of October" \
  --year 2025 \
  --clickup-token "clickup_token" \
  --clickup-assignees 12345 \
  --clickup-listid "11111" \
  --github-token "github_token" \
  --github-orgs "hunterxhunter" \
  --github-include-reviewed-prs

After execution, open the generated report:

reports/report_Uzumaki.Gon_20251030.html

This file (report export) contains the task summary, categorized sections, and AI-rephrased content (if Ollama is available).

For Operations & Business Teams

devreport summary --period <period> --clickup-token "<token>" --clickup-folderid <folder-id>

Word Report Grouped by Module (docs)

Builds the "Individual Report" Word table from local git repositories: commits are grouped into feature modules per codebase (Backend, Web, Mobile…), fixes go under the module they touch, and each module lists the developers who worked on it and the date of its last commit.

./devreport docs \
  --repo "Backend=~/work/iras/pidmis-backend" \
  --repo "Web=~/work/iras/pidmis-frontend" \
  --repo "Mobile=~/work/iras/pidmis-mobile" \
  --start 2026-07-01 --end 2026-09-30 \
  --author "Moses Odeke" --dept "Software Development" \
  --template "Individual Report Template.docx" \
  --llm-provider claude
  • --group llm (default): the LLM names the modules and writes short achievement bullets. Commits it fails to place fall back to path grouping, so nothing is dropped.
  • Challenges: filled in only when commits show a real problem (a crash, revert, rollback, workaround, the same fix repeated), otherwise left empty. In llm mode the model judges this; in path mode commit messages with words like crash, revert, rollback, hotfix, workaround or timeout are used.
  • --group path: no LLM. Modules come from the folders each commit changed (pidmis_gis/ → GIS, src/features/water-network/ → Water Network) and bullets are the cleaned-up commit messages. Quicker, but noisier.
  • --template: the first table in the template is replaced, the rest (header, notes) is kept. Without it a document in the same layout is created.
  • --dev "Moses": only your own commits (matches name or email).
  • --alias "izaiah-m=Izaiah Mukisa": merge a git handle into a name. Handles are also matched to full names automatically from GitHub merge commits, and the run prints every developer with the git identities behind them.
  • Reads all branches by default (--branch main for one), skips merge commits, and counts a repo listed twice only once.

A modules_*.json is saved next to the .docx. Edit it (rename or merge modules, correct challenges, fill in support and follow up) and re-render:

./devreport docs --input reports/modules_20260930_120000.json --template "Individual Report Template.docx"

Or with make: make docs DOCS_REPOS="Backend=~/work/app-backend,Web=~/work/app-web" DOCS_TEMPLATE=template.docx

Supported Periods

Period Description Example
today Current day Tasks created today
yesterday Previous day Tasks created yesterday
this-week or thisweek Current week (Mon-Sun) Tasks from Monday to now
last-week or lastweek Previous week (Mon-Sun) Tasks from last Monday to Sunday
this-month or thismonth Current month Tasks from 1st to now
last-month or lastmonth Previous month Tasks from 1st to last day of previous month
all-time or alltime All time All tasks ever created

Examples

ClickUp Examples

# Weekly report
devreport summary --period this-week --clickup-token "pk_xxx" --clickup-folderid 123456

# Monthly report
devreport summary --period this-month --clickup-token "pk_xxx" --clickup-folderid 123456

# Filter by specific assignees
devreport summary --period this-week --clickup-token "pk_xxx" --clickup-folderid 123456 --clickup-assignees "user1,user2"

# Use environment variables
export CLICKUP_API_KEY="pk_xxx"
export CLICKUP_FOLDERID="123456"
devreport summary --period this-week

GitHub Examples

# GitHub activities report
devreport --user "gon" --start "2025-10-01" --end "2025-10-31" --github-token "ghp_xxx" --github-orgs "hunterxhunter"

# Include reviewed PRs
devreport --user "gon" --start "2025-10-01" --end "2025-10-31" --github-token "ghp_xxx" --github-orgs "hunterxhunter" --github-include-reviewed-prs

# Use environment variables
export GITHUB_TOKEN="ghp_xxx"
export GITHUB_ORGS="hunterxhunter,chimera-ant"
devreport --user "gon" --period this-month