Skip to content

README_en.md

Latest commit

 

History

History
324 lines (225 loc) · 17.8 KB

README_en.md

File metadata and controls

324 lines (225 loc) · 17.8 KB
Raw

code996

code996 is an analysis tool that statistics Git project commit time distribution to deduce the coding work intensity of a project.

It helps you understand new team's working patterns and identify potential overtime culture.

Easy to use, just one command: npx -y code996

English | 简体中文

What's It For

During interviews, we ask about overtime policies, but the answers aren't always truthful. However, code commit times don't lie, which is why this tool exists.

When you join a new company, run npx -y code996 to see the truth behind the data and judge the real overtime culture.

Instead of suffering for three months, better see the truth early! Don't wait until your probation ends to regret!

Features

  • 📊 996 Index: Convert complex overtime situations into intuitive numbers, see project intensity at a glance
  • 🕰️ Smart Working Hours Detection: Estimates standard hours from daily-first-commit percentiles and reports observed evening activity separately
  • 📈 Monthly Trend Tracking: Identify whether the project is "getting more intense" or "stabilizing" through trends
  • 📅 Multi-dimensional Overtime Profile: Comprehensive analysis, identifying not only weekday/weekend overtime peaks but also the overtime ratio of team members
  • 📦 Multi-repo Comparison: One-click scan and analyze multiple repositories under a folder, auto-generate comparisons
  • 🖥️ Local Web Report: Save an offline bilingual visualization alongside the terminal report by default, and use --open to open it automatically
  • 🌍 Cross-timezone Detection: Automatically identify timezone distribution, support specified timezone for precise analysis
  • 🇨🇳 Chinese Holiday Support: Built-in Chinese holiday and makeup workday logic, precisely exclude holiday interference
  • 🔒 Privacy Safe: Pure local execution, offline analysis based on git log

Preview

Core Results

Core Results Preview

Other Module Previews Click to Expand →

Commit Time Distribution

Commit Time Distribution

Overtime Analysis

Overtime Analysis

Monthly Trend Analysis

Monthly Trend Analysis

Team Work Pattern Analysis

Team Work Pattern Analysis

🚀 Quick Start

Use the CLI

First make sure Node.js 18 or newer is installed, then:

# Run in current repo or parent directory of repos
npx -y code996

By default, code996 prints the traditional text report and also saves the visual report under Downloads/code996-report/date_time_project/ without opening a browser, for example Downloads/code996-report/2026-07-18_10-11-46_demo/. Run npx code996 --open to open the generated report automatically. The report remains available after the CLI exits, and deleting that directory removes the whole report. Repository data is never uploaded and no localhost server is required.

You can also install it first so you don't have to re-download every time:

# Global install
npm i -g code996

# Use
code996

Use an AI Coding Agent

No Skill installation is required. Open the target project and send the following prompt to an AI coding agent with network and terminal access:

Read https://raw.githubusercontent.com/hellodigua/code996/main/skills/code996/SKILL.md and its referenced files, then follow the instructions to analyze the current Git project's team work intensity and generate a 996 report.

The AI will use the code996 Skill to collect local Git data and produce a narrative report with overtime semantics, contributor comparisons, and improvement suggestions. You can also replace the final analysis request with:

Analyze our team's overtime situation for 2025 and generate a report
Compare the overtime intensity of /workspace/proj-a and /workspace/proj-b
Analyze this repo with code996 and open the local Web report

Running code996 requires Node.js 18+.

🤖 Smart Analysis Mode

code996 automatically selects the most suitable analysis mode based on context:

  • Running in a Git repo → Single repo deep analysis
  • Multiple repos in directory → Auto-enter multi-repo analysis mode
# Smart detection, auto-select analysis mode
code996                    # Smart detect current environment
code996 /path/to/repo      # Analyze specified repo
code996 /proj1 /proj2      # Auto-enter multi-repo mode
code996 /workspace         # Auto-scan subdirectories

📖 Detailed Usage

Time Range Options

Option Short Description
--year <year> -y Specify year or year range (recommended). Single: 2025; Range: 2023-2025
--since <date> -s Custom start date (YYYY-MM-DD)
--until <date> -u Custom end date (YYYY-MM-DD)
--all-time - Cover entire repository history

Filter & Display Options

Option Short Description
--hours <range> -H Specify standard working hours (e.g., 9-18) ⭐ Recommended for accurate results
--half-hour - Display in half-hour granularity (default hourly) 📊 More precise
--timezone <offset> - Specify timezone (e.g., +0800, -0700) 🌍 For cross-timezone teams
--cn - Force enable Chinese holiday mode (+0800 auto-enabled)
--self - Only count current Git user's commits
--ignore-author <regex> - Exclude authors matching regex (e.g., bot|jenkins)
--ignore-msg <regex> - Exclude commits matching regex (e.g., ^Merge|lint)
--lang <locale> - Specify interface language (zh-CN, en, and common aliases)

Report Output Modes

Option Behavior
Default Print the terminal report and save the Web report without opening a browser
--open Print the terminal report, save the Web report, and open it in a browser
--json / --md Emit stable JSON data or Markdown tables without generating a Web report
--output [path] Save --json or --md to a path; omit the path to use the default filename

--json and --md are mutually exclusive, and --open cannot be combined with either structured output mode. The Web report can switch between Chinese and English from the top-right control; --lang selects the initial language.

Interface Language

code996 automatically selects the interface language based on your computer's system language. Priority:

  1. --lang <locale> CLI option
  2. CODE996_LANG environment variable
  3. Operating system language
  4. Terminal locale (LC_ALL, LC_MESSAGES, LANG)
  5. Node.js Intl locale
  6. English fallback

Currently supported output languages are Chinese and English. Explicit values may be zh, zh-CN, zh_CN, zh-Hans-CN, en, en-US, or en_US. Unsupported explicit values make the command exit with an error.

Usage Examples

# ===== Single Repo Analysis (Smart Mode) =====
code996                        # Analyze current repo (past year)
code996 /path/to/repo          # Analyze specified repo
code996 -y 2025                # Analyze year 2025
code996 -y 2023-2025           # Analyze 2023-2025
code996 -s 2025-01-01 -u 2025-06-30  # Custom date range (first half of year)
code996 --since 2024-07-01     # Analyze from specified date to now
code996 --all-time             # Query entire repo history
code996 --self                 # Only analyze current user's commits
code996 --self -y 2025         # Analyze your commits in 2025

# ===== Multi-repo Analysis (Smart Auto-detect) =====
code996                        # If subdirs have multiple repos, auto-enter multi-repo mode
code996 /path/proj1 /path/proj2  # Pass multiple paths, auto-analyze multiple repos
code996 /workspace             # Scan all sub-repos in specified directory
code996 /workspace -y 2025     # Analyze 2025 data and trends
code996 --self                 # Only count current user's commits across all repos

# Specify Working Hours (Recommended)
code996 --hours 9.5-18.5       # Specify 9:30-18:30 (supports decimals)
code996 --hours 9.5-19 -y 2025 # Combine with year analysis

# Fine-grained Analysis (Half-hour Granularity)
code996 --half-hour            # Display time distribution in half-hour granularity
code996 -y 2025 --half-hour    # Combine with year analysis, fine display
code996 /proj1 /proj2 --half-hour  # Multi-repo analysis, half-hour granularity

# Cross-timezone Project Analysis
code996 --timezone="+0800"     # Only analyze commits from UTC+8 (China)
code996 --timezone="-0700"     # Only analyze commits from UTC-7 (US West Coast)
code996 -y 2025 --timezone="+0800"  # Analyze 2025 commits in specific timezone

# Chinese Holiday Makeup Workday Analysis
code996                        # System auto-enables holiday mode when primary timezone is +0800
code996 --cn                   # Manually force enable holiday mode (for non +0800 timezone projects)
code996 --timezone="-0700" --cn # Analyze non-China timezone project but judge by Chinese holidays

# Filter Noise Data (Exclude CI/CD bots, merge commits, etc.)
code996 --ignore-author "bot"                    # Exclude all authors containing "bot"
code996 --ignore-author "bot|jenkins|github-actions"  # Exclude multiple authors (use | to separate)
code996 --ignore-msg "^Merge"                    # Exclude all commit messages starting with "Merge"
code996 --ignore-msg "merge|lint|format"         # Exclude multiple keywords
code996 -y 2025 --ignore-author "renovate|dependabot" --ignore-msg "^Merge" # Combined filter

# Specify interface language
code996 --lang zh-CN          # Force Chinese UI
code996 --lang en             # Force English UI

# Report output
code996                       # Print the terminal report and save the Web report without opening it
code996 --open                # Print the terminal report, save the Web report, and open it
code996 --json --output report.json
code996 --md --output report.md

Common Exclusion Scenarios:

# Exclude all CI/CD bots
--ignore-author "bot|jenkins|github-actions|gitlab-ci|circleci|travis"

# Exclude dependency update bots
--ignore-author "renovate|dependabot|greenkeeper"

# Exclude merge and formatting commits
--ignore-msg "^Merge|^merge|lint|format|prettier"

# Exclude auto-generated commits
--ignore-msg "^chore|^build|^ci|auto"

How It Works

  1. Use git-log to get project commit related data
  2. Compute the analysis locally and build one shared ReportData payload
  3. Print the terminal report and save the Web page by default, or explicitly open Web / emit JSON / Markdown

Data Collection Flow

Git Repo → git log collection → Daily first commit + Hourly distribution → Percentile estimation of start/end work → 996 Index calculation → Result output

Key Algorithms

  1. Time Distribution Analysis:
    • Data collection: Collect commit times at minute-level, auto-aggregate into 48 half-hour points
    • Algorithm processing: Preserve half-hour boundaries for standard hours and the 996 index; only observed activity-end diagnostics use hourly aggregation
    • Display mode: Default hourly display (24 points), optional half-hour mode (48 points)
  2. Work Time Identification: Use the 10%-20% percentile of recent daily-first-commit samples to estimate the start time, then use a fixed nine-hour standard window; report observed evening activity separately without expanding normal hours
  3. 996 Index Calculation: Build index based on overtime ratio, output Chinese description
  4. Project Type Identification: Through work time regularity, weekend activity, evening activity patterns, auto-identify whether project is "corporate project" or "open source project"
  5. Cross-timezone Collaboration Detection: Identify cross-timezone projects through timezone dispersion and "sleep period" commit ratio (threshold: non-dominant timezone >1%), provide timezone filter suggestions
  6. Holiday Makeup Workday Recognition: When primary timezone is +0800 and accounts for >50%, auto-enable Chinese holiday judgment (workday/weekend considers legal holidays and makeup workdays), other timezones can manually enable via --cn parameter
  7. Data Validation: Verify statistical data matches total commit count, avoid deviation from missing data
  8. Uncertainty Reporting: When automatic work-hour confidence is below 60%, report an index range across common schedules instead of presenting a low-sample estimate as certain

Usage Tips

  • Privacy Protection: All Git data analysis is performed locally, no results or logs are uploaded.
  • Analysis Limitations: The tool only counts commit times in git log. However, actual work also includes meetings, learning, maintaining documentation, debugging, testing, etc. Therefore, reports cannot cover all actual work time, analysis results have limited accuracy, please use with caution.
  • Usage Restrictions: This project's analysis results are for personal reference only, please do not use for "evil" or improper purposes.
  • Disclaimer: code996 is not responsible for any consequences caused by using, distributing this program and its derivatives.

Anonymous Contributions

If you'd like to help calibrate code996's calculations, run the following command in the Git repository you want to analyze:

npx code996 benchmark

The command analyzes the repository locally and uploads nothing. It creates an unlabeled code996-benchmark-*.json file; open and review the file before sending it to the maintainer. Unlabeled samples can expose obvious algorithm failures and unusual distributions, but cannot prove the error against the team's actual schedule.

Optionally provide context to create a labeled sample that is more useful for measuring error:

npx code996 benchmark \
  --reference-hours 9.5-18.5 \
  --team-size 20
  • --reference-hours: the team's actual or typical standard hours, used to compare against the automatic result
  • --team-size: used only to study algorithm behavior by team-size segment; it does not affect the 996 index, and the Git contributor-count bucket is still collected automatically when omitted
  • --schedule and --label-confidence: optional schedule and reference-label context
  • -y / --since --until: use a fixed range so datasets can be reproduced and compared

The JSON contains no private information. It retains commit counts, half-hour and weekday aggregate distributions, the month range, a contributor-count bucket, and the automatic result; reference results and error fields appear only when reference hours are supplied.

Other Questions

Here are some common questions. If you have other questions, feel free to open an issue.

💡 Need code to analyze, isn't it too late to use after joining?

Not really. The core value of code996 is breaking information asymmetry, using real data to counter verbal promises.

  1. Probation is "inspection period": Joining doesn't mean selling yourself. The legal probation period is also our inspection period for the company. If you find it's a pit on day one, cutting losses early is also an avoidance strategy.
  2. Background check during referral: Think bigger! You can totally ask your inside friend at that company to run it for you. Isn't that the most hardcore referral background check? 🐶
  3. Decision basis: Even after joining, having solid overtime evidence in hand, whether to use it as reason for transfer, or as basis for resignation decision, is much better than self-doubt.

📉 Will Squash commits affect accuracy if the project habit is local multiple commits then Squash before push?

There will be some impact, but code996 relies on statistical patterns. As long as commit samples reach a certain number, what's finally shown is the team's collective work pattern, special commit habits will be filtered out as "noise" statistically.

🚀 What's the project roadmap?

Future features will follow the WLB and work pit-avoidance line, including: more refined overtime ratio analysis, and analyzing code's shit-mountain index (complexity analysis), after all maintaining shit-mountains is also one of the culprits of 996.

AI Collaboration

🤖 Note for AI Collaboration Partners: This project adopts standardized AI collaboration workflow, please check .docs/README.md for collaboration guidelines.

📄 License

MIT License