npm-git-helper

The Git CLI that writes your commit messages. Stage, commit (with AI), and push — in one command.

You type the same three git commands fifty times a day. git-helper collapses them into one, and — if you set an API key — lets Claude or GPT write the commit message for you from the staged diff.

$ git-helper push --ai
→ Staging 4 change(s)
→ Asking anthropic to draft a commit message…

fix(auth): handle expired tokens in refresh flow

- return 401 instead of 500 when the refresh token is past its
  exp claim, so the client can re-authenticate cleanly

? Use this message? [Y/n] y
→ Committing: fix(auth): handle expired tokens in refresh flow
→ Pushing to origin/fix-auth
✓ Pushed successfully.

No API key? You still get an interactive Conventional Commit wizard, a one-shot WIP commit, safe undo, sync, amend, and a pr shortcut.

Install

npm install -g npm-git-helper

Requires Node.js 18+ and a working git binary.

Quickstart

# AI-drafted commit message
export ANTHROPIC_API_KEY=sk-...      # or OPENAI_API_KEY
git-helper push --ai

# Plain push
git-helper push -m "feat: add login"

# Interactive (Conventional Commit wizard) — runs when no message given
git-helper push

# Save a quick "wip" commit so you can switch branches
git-helper wip

# Pull latest and rebase your work onto it
git-helper sync --autostash

# Undo the last commit (keeps your changes staged)
git-helper undo

# Fix the last commit and force-push safely
git-helper amend -m "fix: typo" --force

# Push and open a PR (needs `gh`)
git-helper pr --draft

Commands

| Command | What it does | | --- | --- | | push | Stage all changes, commit (AI / interactive / -m), push with smart upstream tracking | | sync | Fetch + rebase the current branch onto its remote; --autostash and --push flags | | wip | Quick wip: <timestamp> commit so you can switch branches without losing work | | undo | Soft-reset the last commit (keeps changes staged); --hard to discard | | amend | Restage and amend the last commit; --force does a safe --force-with-lease push | | pr | Push the current branch and open a PR via gh (--draft, --title, --body, …) |

Every command has --help.

AI commits

Set one of these env vars and pass --ai to push:

| Provider | Env var | Default model | Override with | | --- | --- | --- | --- | | Anthropic | ANTHROPIC_API_KEY | claude-haiku-4-5-20251001 | GIT_HELPER_MODEL | | OpenAI | OPENAI_API_KEY | gpt-4o-mini | GIT_HELPER_MODEL |

git-helper only sends the staged diff (truncated to 12k chars). It prompts you to accept, edit, or reject the suggestion — nothing is committed without your confirmation. The output is Conventional Commits by design.

Safety

• No git add ./*. Uses git add -A so deletions, renames, and dotfiles are correctly captured.
• Protected branches confirm before push. main, master, production, release — pass --yes to skip.
• --force means --force-with-lease. No silent overwrites of teammates' work.
• sync --autostash stashes before rebase and restores after; failure leaves the stash intact.
• undo defaults to soft. Your changes are kept staged; --hard requires confirmation.

Why not just use aliases / gh?

• Aliases can't prompt you, generate messages, or chain stage → commit → push with branch handling.
• gh is for GitHub workflows; this is for the local loop you run before you ever touch the PR.
• commitizen requires hooks and config; this works in any repo, instantly.

Configuration (optional)

Drop a .git-helperrc (JSON) at the repo root for defaults:

{
  "protectedBranches": ["main", "release"],
  "defaultBranch": "main"
}

Programmatic use

const { runPush } = require("npm-git-helper/lib/commands/push");
await runPush({ message: "chore: bump deps", branch: "deps" });

Contributing

Issues and PRs welcome at github.com/Leslie-23/git-helper. Run the test suite with npm test (uses Node's built-in test runner, no extra setup).

License

ISC © Leslie Paul Ajayi

Links

• npm package
• GitHub repo
• Changelog
• Report a bug