io.github.CloudCorpRecords/branchname

branchname

Naming a branch sounds trivial until every contributor does it differently: fix-login, 123-login-bug, johns-branch, and a dozen variants of the same issue, none of them greppable in the same way. branchname takes the other approach — you hand it the issue, and it hands back one name, built the repo's way every time.

The title is slugified by a fixed, pinned recipe: lowercase it, replace every maximal run of characters outside [a-z0-9] with a single -, and strip leading and trailing -. Punctuation clusters collapse instead of multiplying, digits survive, and characters outside ASCII — accents, dashes, emoji — count as separators like any other punctuation. A title with nothing slugifiable in it at all is an error ("title produces an empty slug"), not a branch named -.

When the slug runs long, it is truncated: cut to exactly max_slug_length characters (40 by default, never below 8), then strip any trailing - the cut left behind, so a branch never ends mid-word on a dangling hyphen.

The slug is then composed in one of four conventions:

• type-issue-slug (the default) — <type>/<issue_number>-<slug>, for example fix/123-login-redirect-loop. Requires both type and issue_number.
• type-slug — <type>/<slug>, for example docs/update-install-guide. Requires type.
• issue-slug — <issue_number>-<slug>, for example 42-login-redirect-loop. Requires issue_number.
• slug — just <slug>, for example login-redirect-loop. Requires neither.

type is one of feat, fix, chore, docs, refactor, or test. Asking a convention for a component you did not supply is an error naming that component, and malformed input — a missing, empty, or non-string title, an issue_number that is not an integer of at least 1, a type or convention outside its enum, or a max_slug_length that is not an integer of at least 8 — is a validation error naming the offending path, with no partial result. The computation is pure and local: no network, no configuration, and no repository is read or touched — branchname only builds the name.

CLI

npx @reneturcios/branchname make --input args.json
npx @reneturcios/branchname --version

args.json contains the full arguments object:

{
  "title": "Fix login redirect loop",
  "issue_number": 123,
  "type": "fix"
}

convention defaults to "type-issue-slug" and max_slug_length defaults to 40. The result is printed as JSON:

{
  "branch": "fix/123-fix-login-redirect-loop",
  "slug": "fix-login-redirect-loop",
  "convention": "type-issue-slug"
}

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/branchname mcp

MCP client config:

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

Tools

• make_branch_name — Build a branch name from an issue title.

  • title (string, required, non-empty) — the issue title to slugify
  • issue_number (integer, optional, at least 1) — the issue number
  • type (string, optional) — change type prefix, one of feat, fix, chore, docs, refactor, test
  • convention (string, optional, default "type-issue-slug") — one of type-issue-slug, type-slug, issue-slug, slug
  • max_slug_length (integer, optional, default 40, at least 8) — maximum slug length before truncation

  Returns {branch, slug, convention}, where slug is the final (possibly truncated) slug and convention echoes the resolved convention.

Docker

docker run -i ghcr.io/cloudcorprecords/branchname
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/branchname make --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