██████╗ ███████╗██████╗  ██████╗     ████████╗██╗███╗   ███╗███████╗
  ██╔══██╗██╔════╝██╔══██╗██╔═══██╗    ╚══██╔══╝██║████╗ ████║██╔════╝
  ██████╔╝█████╗  ██████╔╝██║   ██║       ██║   ██║██╔████╔██║█████╗
  ██╔══██╗██╔══╝  ██╔═══╝ ██║   ██║       ██║   ██║██║╚██╔╝██║██╔══╝
  ██║  ██║███████╗██║     ╚██████╔╝       ██║   ██║██║ ╚═╝ ██║███████╗
  ╚═╝  ╚═╝╚══════╝╚═╝      ╚═════╝        ╚═╝   ╚═╝╚═╝     ╚═╝╚══════╝

See your repo's future before it breaks.

RepoTimeMachine is a global npm CLI that scans GitHub and local repositories to forecast future maintenance risks using git history, file complexity, test gaps, ownership patterns, and dependency centrality.

Quick Install

npm install -g repotimemachine

Then run:

# Scan local repo
rtm scan .

# Scan any public GitHub repo
rtm scan https://github.com/user/repo

# Quick health score
rtm score .

# Explain a specific file
rtm explain src/auth/session.ts

# Generate issue drafts
rtm issues . --output issues.md

# CI mode with thresholds
rtm ci . --max-risk 75 --fail-on-critical

# AI summaries (optional)
export GROQ_API_KEY="gsk_your_key"
rtm scan . --ai

Commands

| Command | Description | |---------|-------------| | rtm scan [repo] | Full analysis with future-risk forecast | | rtm score [repo] | Quick health score only | | rtm explain <file> | Detailed risk breakdown for a file | | rtm issues [repo] | Generate GitHub issue drafts | | rtm timeline [repo] | Historical risk timeline with ASCII chart | | rtm compare <base> <target> [repo] | Compare risk between git refs | | rtm watch [repo] | Watch mode — re-analyze on file changes | | rtm ci [repo] | CI mode with exit codes (GitHub Actions) | | rtm badge [repo] | Generate README health badge | | rtm doctor | Check environment readiness | | rtm init | Create .repotimemachine.json config |

Scan Options

| Option | Default | Description | |--------|---------|-------------| | --horizon | 6m | Forecast horizon: 3m, 6m, 12m | | --format | text | Output: text, markdown, json | | --output | — | Save report to file | | --max-files | 1500 | Max files to analyze | | --since | 180d | Git history window | | --ai | — | Enable AI summaries (requires GROQ_API_KEY) | | --model | llama-3.1-8b-instant | AI model | | --no-banner | — | Hide ASCII banner | | --debug | — | Show debug logs |

Scoring Methodology

RepoTimeMachine computes risk using five deterministic signals:

| Signal | Weight | What It Measures | |--------|--------|-----------------| | Churn | 28% | How often files change | | Complexity | 22% | Lines, imports, functions | | Test Gap | 20% | Missing tests for high-risk files | | Ownership | 15% | Single-contributor concentration | | Centrality | 15% | Import dependency bottlenecks |

Risk Categories

| Score | Category | |-------|----------| | 0–30 | Low | | 31–55 | Moderate | | 56–75 | High | | 76–100 | Critical |

AI with Groq (Optional)

Set GROQ_API_KEY for natural-language summaries:

export GROQ_API_KEY="gsk_your_key"
rtm scan . --ai

What AI provides:

• Executive Summary — natural-language health overview
• Failure Mode Prediction — what will break first
• Smarter Recommendations — context-aware next steps
• Suggested Issue Wording — draft GitHub issues

AI only sends compact risk metadata — never source code.

CI Usage (GitHub Actions)

name: RepoTimeMachine
on: [pull_request]
jobs:
  repo-risk:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npm install -g repotimemachine
      - run: rtm ci . --max-risk 75 --fail-on-critical

Configuration

Create .repotimemachine.json (use rtm init):

{
  "horizon": "6m",
  "since": "180d",
  "maxFiles": 1500,
  "exclude": ["node_modules/**", "dist/**", "build/**"],
  "weights": {
    "churn": 0.28,
    "complexity": 0.22,
    "testGap": 0.20,
    "ownership": 0.15,
    "centrality": 0.15
  }
}

Example Output

╭─ Forecast ─────────────────────────────────────────╮
│ Repository       my-app                             │
│ Horizon          6 months                           │
│ Health Score     64/100                             │
│ Future Risk      High                               │
│ Failure Mode     Test gaps around high-churn code   │
╰────────────────────────────────────────────────────╯

Top Future Risks
┌────┬───────────────────────────────┬──────┬──────────────┐
│ #  │ File                          │ Risk │ Main Reason  │
├────┼───────────────────────────────┼──────┼──────────────┤
│ 1  │ src/auth/session.ts           │ 87   │ Test Gap     │
│ 2  │ src/billing/stripe.ts         │ 82   │ Churn        │
│ 3  │ src/lib/router.ts             │ 78   │ Centrality   │
└────┴───────────────────────────────┴──────┴──────────────┘

Supported Languages

TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, PHP, Ruby, C#, C/C++, Swift

Security

See SECURITY.md for details on privacy and data handling.

Publishing

See PUBLISHING.md for npm publishing instructions.

License

MIT