devrec

A CLI tool that analyzes git commits from multiple repositories, categorizes them, and generates summaries in markdown.

Installation

From npm

npm install -g devrec

From source

git clone <repo-url>
cd devrec
npm install
npm run build
npm link

Verify installation

drec --version

Quick start

1. Initialize configuration

   drec init

   This command interactively prompts you for:

   • Your git email addresses
   • Repository paths to track
   • Main branch name (default: main)
   • Branch scanning strategy (all or remote-only)

2. View today's commits

   drec today

3. Generate markdown summary

   drec today --format markdown --summary

Usage

Commands

drec init

Create or update configuration interactively.

drec today

Show commits from today (since midnight).

drec yesterday

Show commits from yesterday (previous calendar day).

drec week

Show commits from current week (Monday to today). On Monday, shows the previous complete week (last Monday to Sunday).

drec sprint

Show commits from current sprint. Sprint length is configurable (default: 2 weeks).

drec all

Show all commits from all time.

Flags

All time-range commands support these flags:

| Flag | Description | Values | Default | | ------------- | ------------------------------------------- | --------------------------- | ------- | | --format | Output format | plain, markdown | plain | | --color | Color mode | always, never, auto | auto | | --summary | Show statistics | (boolean) | false | | --repo | Filter by repository | Repository name from config | All | | --category | Filter by category | Category name | All | | --highlight | Boost matching commits to Key Contributions | Branch name or keyword | None |

Categories

Commits are automatically categorized based on prefixes:

• Feature: feat:, feat/, feat(
• Bug: fix:, fix/, fix(, bugfix:
• Refactor: refactor:, refactor/, refactor(
• Test: test:, test/, test(
• Chore: chore:, chore/, chore(
• Documentation: docs:, docs/, docs(, documentation:
• CI: ci:, ci/, ci(
• Other: Commits not matching any pattern

Merge commits are automatically excluded. Jira-formatted commits (such as Resolve TICKET-123 "message") are handled by extracting the actual message for categorization.

Importance scoring

Commits are automatically scored by importance and grouped into tiers:

• Key Contributions (high + medium importance) -- surfaced at the top of the output
• Other Work (low importance) -- shown below

Importance is determined by two signals:

| Signal | High | Medium | Low | | ------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- | --------------- | | Keywords in message | security, critical, breaking, hotfix, vulnerability, urgent | performance, migration, deprecate, regression | Everything else | | Merge status | -- | Merged to main | Unmerged |

The two signals combine: a medium keyword on a merged commit becomes high. A commit with no keywords that is merged becomes medium.

The --highlight flag lets you manually override scoring: any commit whose message or branch matches the given value is force-boosted to high importance, bypassing the automatic scoring logic. The match is a case-insensitive substring check.

Tier headers only appear when both tiers have commits. When all commits land in a single tier, the output renders flat without tier headers.

Within the output, merged commits are prefixed with a checkmark, while unmerged commits show their branch name.

Configuration

Configuration is stored at ~/.config/devrec/config.json.

Schema

{
  "authorEmails": ["[email protected]"],
  "branchStrategy": "all",
  "groupBy": "repo",
  "locale": "en-US",
  "mainBranch": "main",
  "repos": [
    {
      "name": "my-project",
      "path": "/Users/you/projects/my-project"
    }
  ],
  "sprintLength": 2
}

See docs/sample-config.json for a complete example.

Fields

| Field | Type | Description | Default | | ---------------- | ------------------------ | ------------------------------------------------------ | --------- | | authorEmails | string[] | Git email addresses to filter commits | Required | | repos | Repo[] | Repositories to scan | Required | | sprintLength | number | Sprint duration in weeks | 2 | | groupBy | "repo" | "category" | How to group output | "repo" | | locale | string | Date formatting locale (for example, en-US, it-IT) | "en-US" | | mainBranch | string | Main branch name for merge tracking | "main" | | branchStrategy | "all" | "remote" | Which branches to scan | "all" |

Repo schema

{
  "mainBranch": "main",
  "name": "project-name",
  "path": "/absolute/path/to/repo"
}

The mainBranch field is optional and overrides the global mainBranch setting for this specific repository.

Branch strategy

• all: Scans all local and remote branches
• remote: Scans only remote branches (commits pushed to origin)

Use remote to exclude local work-in-progress commits.

Examples

Daily standup report

drec today --format markdown --summary

Output:

# Dev Log: February 17, 2026

## Summary

- **Total Commits**: 8
- **Merged to Main**: 5
- **In Progress**: 3
- **Key Contributions**: 3
- **Repositories**: api, web-app

---

## Key Contributions

### Feature

#### api

    - ✓ [a1b2c3d] feat: add user authentication endpoint _(8:30 AM)_
    - ✓ [d4e5f6a] feat: implement rate limiting _(9:15 AM)_

### Bug

#### api

    - [g7h8i9j] fix: critical login vulnerability `[hotfix/login]` _(10:00 AM)_

## Other Work

### Feature

#### web-app

    - [k0l1m2n] feat: add dashboard analytics `[feature/analytics]` _(11:00 AM)_

### Chore

#### api

    - ✓ [o3p4q5r] chore: update dependencies _(2:00 PM)_

Sprint retrospective

drec sprint --format markdown --summary > sprint-summary.md

This command generates a markdown file containing all commits from the current sprint.

Filter specific repository

drec week --repo api

Shows only commits from the repository named "api" in your config.

Filter by category

drec week --repo api --category Feature

Shows only Feature commits from the "api" repository.

Highlight specific work

drec week --highlight feat/auth

Boosts any commit whose message or branch contains "feat/auth" to Key Contributions, regardless of automatic scoring.

View all commits

drec all --summary

Shows all commits from all repositories with summary statistics.

Troubleshooting

Config not found

Error: Config file not found

Solution: Run drec init to create configuration.

Invalid repository path

Error: Not a git repository

Solution: Ensure the path in config.json points to a git repository root (contains .git/).

No commits found

Possible causes:

• Author email doesn't match git config
• No commits in date range
• Wrong branch strategy (try "all" instead of "remote")

Check your git email:

git config user.email

Ensure this email matches one of the emails in your authorEmails array.

Permission denied

Error: No read permission

Solution: Check file permissions on repository path:

ls -la /path/to/repo

Colors not working

Solution: Force color mode:

drec today --color always

Slow performance with many repos

Solutions:

• Use --repo flag to filter to specific repositories
• Use branchStrategy: "remote" in config to scan fewer branches
• Reduce date range with specific commands (today versus all)

Acknowledgments

Built with:

• Commander.js - CLI framework
• simple-git - Git operations
• Zod - Schema validation
• Inquirer - Interactive prompts
• Chalk - Terminal colors