io.github.CloudCorpRecords/gitcleanplan

gitcleanplan

Branch lists grow quietly. A feature lands, its branch stays; an experiment is abandoned, its branch stays too; the upstream disappears and the local copy lingers. Deleting branches on a hunch is how work gets lost, so gitcleanplan takes the middle road: you hand it the branch data, and it hands back a plan — lists first, deletes nothing.

For every branch you supply, the plan gives one of three decisions, each with the reason that produced it:

• keep — the default branch, a protected branch, the branch currently checked out, or a branch that is simply still active.
• review — merged but recently active, upstream gone but not merged, or stale but not merged: promising cleanup candidates that deserve a human look before anything else.
• delete — merged and either its upstream is gone or it has been stale for at least stale_days. Only merged branches can ever land here.

Decisions follow a fixed rule order, so the reason is never ambiguous: the default branch wins over protection, protection wins over a merged-and-gone branch, being checked out wins over being merged, and "merged and upstream is gone" wins over "merged and stale". Staleness is inclusive — a branch whose last commit was exactly stale_days ago counts as stale.

Alongside the per-branch decisions, the result groups the branch names under each action, counts them, and lists one safe-delete command (git branch -d <name>) per branch planned for deletion, in name order. Those commands are listed, never run: gitcleanplan does not invoke git, open a repository, or delete anything. You read the plan, and you decide what to execute yourself.

Malformed input — a missing or empty branch list, a missing, empty, or duplicated branch name, a missing, negative, or non-integer last_commit_days_ago, a wrongly typed flag, a bad stale_days or default_branch — is a validation error naming the offending path (for example branches[1].last_commit_days_ago must be an integer >= 0), and no partial plan is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/gitcleanplan plan --input args.json
npx @reneturcios/gitcleanplan --version

args.json contains the full arguments object:

{
  "stale_days": 90,
  "branches": [
    { "name": "main", "last_commit_days_ago": 0, "current": true },
    { "name": "shipped-feature", "merged": true, "upstream_gone": true, "last_commit_days_ago": 45 },
    { "name": "old-spike", "last_commit_days_ago": 180 }
  ]
}

merged, upstream_gone, protected, and current default to false per branch; stale_days defaults to 90; default_branch defaults to "main". The plan is printed as JSON:

{
  "branches": [
    { "name": "main", "action": "keep", "reason": "default branch" },
    { "name": "old-spike", "action": "review", "reason": "stale but not merged" },
    { "name": "shipped-feature", "action": "delete", "reason": "merged and upstream is gone" }
  ],
  "plan": {
    "delete": ["shipped-feature"],
    "review": ["old-spike"],
    "keep": ["main"]
  },
  "counts": { "delete": 1, "review": 1, "keep": 1 },
  "commands": ["git branch -d shipped-feature"]
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/gitcleanplan mcp

MCP client config:

{
  "mcpServers": {
    "gitcleanplan": {
      "command": "npx",
      "args": ["-y", "@reneturcios/gitcleanplan", "mcp"]
    }
  }
}

Tools

• plan_branch_cleanup — Plan stale and merged branch cleanup.

  • branches (array, required, at least one) — branches as {name, last_commit_days_ago, merged?, upstream_gone?, protected?, current?} objects; name is unique across the set and last_commit_days_ago is a whole-day count of at least 0
  • stale_days (integer, optional, default 90, at least 1) — a branch is stale at this many days since its last commit
  • default_branch (string, optional, default "main") — the default branch name; it is never planned for deletion

  Returns {branches, plan, counts, commands}.

Docker

docker run -i ghcr.io/cloudcorprecords/gitcleanplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/gitcleanplan plan --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios