commitclinic 0.1.1

Repository triage CLI for migration readiness and cleanup planning

CommitClinic

CommitClinic is a repository migration triage CLI. It diagnoses Git repositories (and legacy repos once mirrored to Git), scores migration readiness, and plans safe treatment actions.

Vibe

CommitClinic uses a medical triage voice:

• Intake: collect repository baseline.
• Diagnosis: identify risk findings.
• Severity: assign A-F readiness grade.
• Treatment Plan: propose cleanup actions.
• Discharge: final migration readiness status.

Install

From PyPI (recommended):

pipx install commitclinic

From source (local dev):

git clone https://github.com/your-org/commitclinic
cd commitclinic
pipx install .

That's it. commitclinic is now available everywhere in your terminal. No venv activation needed — pipx manages the isolation automatically.

If you don't have pipx: brew install pipx && pipx ensurepath

Install helper tools (BFG + TruffleHog):

commitclinic install-tools

Quick Start

1. Run intake + diagnosis:

commitclinic intake --repo /path/to/repo --json-out reports/findings.json --csv-out reports/findings.csv

3. Print scoring summary:

commitclinic diagnose --input reports/findings.json

Core Commands

• commitclinic intake: scan a repository and generate findings.
• commitclinic diagnose: compute score and grade from findings JSON.
• commitclinic treatment-plan: generate remediation suggestions.
• commitclinic treat: execute approved history cleanup actions.
• commitclinic install-tools: install optional helper tools (such as BFG).
• commitclinic discharge: produce final readiness summary.
• commitclinic batch: scan multiple repositories from a local paths file.
• commitclinic scan-list: clone and scan repos from a JSON URL list.
• commitclinic ui: launch an interactive terminal dashboard.

commitclinic treat is destructive. It requires --approve and should be run only after backup.

BFG Support

CommitClinic supports BFG as a treatment backend.

1. Install BFG jar via CommitClinic:

commitclinic install-tools --with-bfg

2. Run treatment with BFG:

commitclinic treat --repo /path/to/repo --backend bfg --strip-path secrets.txt --approve

Notes:

• BFG deletes by filename pattern; exact path deletions are best handled with git-filter-repo.
• You can set BFG_JAR=/path/to/bfg-1.14.0.jar in CI/local environments to pin the jar.

Terminal TUI

Run the interactive terminal dashboard:

commitclinic ui --repo /path/to/repo

Shorter launch options also work:

commitclinic ui
commitclinic tui
commitclinic dashboard

If --repo is omitted, CommitClinic uses the current directory.

Keyboard controls:

• i: run intake
• d: refresh diagnosis
• p: preview treatment plan
• w: write report JSON to temp directory
• j/k or arrow keys: move selected finding
• t: run treatment for selected finding path (prompts for y confirmation)
• q: quit

The TUI is intended for local triage sessions. Use standard non-interactive commands in CI and GitHub Actions.

TUI treatment notes:

• The t action uses git-filter-repo for selected finding paths.
• If selected finding has no path location, treatment is blocked.

TruffleHog Integration

If trufflehog is installed and available in PATH, CommitClinic runs it automatically during intake. If not installed, CommitClinic logs a non-blocking warning finding so you can still run a full pipeline.

Scanning a List of Remote Repos

Create a JSON file with the repos you want to audit:

{
  "repos": [
    { "url": "https://github.com/org/repo-one", "name": "repo-one" },
    { "url": "https://github.com/org/repo-two", "name": "repo-two" }
  ]
}

A flat array of URL strings also works:

["https://github.com/org/repo-one", "https://github.com/org/repo-two"]

Run the scan:

commitclinic scan-list repos.json --work-dir ~/scratch/clones

Results are written to repos.results.json (alongside the list file) after each repo, so if the process is interrupted mid-list you don't lose progress. Re-running skips repos that are already in the results file. Use --refresh to re-scan everything.

# Custom output path:
commitclinic scan-list repos.json --out results/audit.json

# Exit 2 if any repo has blocking findings (useful in CI):
commitclinic scan-list repos.json --strict

# Re-scan all, even previously scanned:
commitclinic scan-list repos.json --refresh

GitHub Actions

Starter workflows are included:

• .github/workflows/commitclinic-audit.yml
• .github/workflows/commitclinic-pr.yml
• .github/workflows/commitclinic-summary.yml