Gitflow-helper is a tool designed to enforce the git-flow branching model through an interactive text-based user interface (TUI) for human users and a JSON mode tailored for AI agents. It automatically detects your integrated development environment (IDE), such as Cursor or VS Code Copilot, and generates pre-flight rules to ensure compliance with specified workflows.
Key Features:
16 CLI Commands: Covers the entire gitflow lifecycle, including status checks, pull/push operations, feature/bugfix/release/hotfix branch management, cleanup, and health audits.
Interactive TUI: Offers a dashboard, action menu, command palette, and help overlay for intuitive navigation and execution of commands.
JSON Mode: Facilitates seamless integration with AI agents like Cursor, Copilot, Claude Code, etc., enabling machine-readable output for automated processes.
IDE Integration: Automatically generates rules for .cursor/rules/, .github/copilot-instructions.md, or AGENTS.md based on detected IDE, ensuring consistent workflow adherence.
Zero Runtime Dependencies: Operates as a static binary requiring only Git, eliminating the need for additional software installations.
Cross-Platform Support: Available for Linux (x86_64, arm64), Windows (x86_64), and macOS (universal binary supporting x86 and ARM architectures).
Audience & Benefit:
Ideal for developers, DevOps engineers, and project managers utilizing the git-flow model. Gitflow-helper enforces best practices, automates pre-flight checks for AI agents, integrates seamlessly across platforms, and reduces manual overhead through its comprehensive command set and TUI interface.
Installation can be efficiently handled via winget, ensuring a smooth setup process.
README
gitflow-helper
A single static binary that enforces the git-flow branching model with an interactive TUI for humans and a --json mode for AI agents. Detects your IDE (Cursor / VS Code Copilot) and generates pre-flight rules automatically.
Download the latest binary for your platform from the Releases page.
# macOS Apple Silicon (arm64)
curl -LO https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow--darwin-arm64.tar.gz
tar -xzf gitflow--darwin-arm64.tar.gz
sudo install -m 755 gitflow /usr/local/bin/gitflow
# Linux x86_64 (tarball fallback)
curl -LO https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow--linux-amd64.tar.gz
tar -xzf gitflow--linux-amd64.tar.gz
sudo install -m 755 gitflow /usr/local/bin/gitflow
# Linux arm64 / aarch64 (tarball fallback)
curl -LO https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow--linux-aarch64.tar.gz
tar -xzf gitflow--linux-aarch64.tar.gz
sudo install -m 755 gitflow /usr/local/bin/gitflow
# Windows x86_64
# Download gitflow--windows-amd64.zip and add gitflow.exe to PATH
If you prefer native Linux packages instead of tarballs, use the APT or DNF/YUM repo setup above.
From Source
go install github.com/novaemx/gitflow-helper/cmd/gitflow@latest
Build Locally
git clone https://github.com/novaemx/gitflow-helper.git
cd gitflow-helper
bash scripts/install-hooks.sh # install git hooks (enforces gitflow policy)
make build # current platform
make build-all # all platforms
make universal # macOS universal binary
Quick Start
# Initialize gitflow in your project
gitflow init
# Auto-detect your IDE and generate rules
gitflow setup
# Launch the interactive TUI
gitflow
Usage
Interactive TUI
Run gitflow without arguments to launch the full-screen dashboard:
j/k or arrow keys to navigate
Enter to execute an action
/ to open the command palette (type to filter)
? for help
r to refresh
q to quit
CLI Commands
All commands support --json for machine-readable output.
Use --log to write troubleshooting output to .gitflow/logs/gitflow.log. Add --debug to include verbose debug details in the same file.
gitflow status # repo state dashboard
gitflow status --log # write troubleshooting logs to .gitflow/logs/gitflow.log
gitflow status --log --debug # include verbose debug details in the log file
gitflow pull # safe fetch + fast-forward merge
gitflow push # push current branch (target-aware)
gitflow push develop # push current branch to target branch with validation
gitflow start feature my-feature # start a feature branch
gitflow start bugfix fix-name # start a bugfix branch
gitflow start release 1.2.0 # start a release
gitflow start hotfix 1.1.1 # start a hotfix
gitflow finish # finish current flow branch
gitflow sync # sync branch with parent
gitflow switch develop # switch to a branch
gitflow backmerge # merge main into develop
gitflow cleanup # delete merged branches
gitflow health # full repo health audit
gitflow doctor # validate prerequisites
gitflow log -n 20 # gitflow-aware commit log
gitflow undo # undo last operation (reflog)
gitflow releasenotes # generate RELEASE_NOTES.md
gitflow diagram # print Mermaid branch topology diagram
gitflow diagram -o graph.mmd # write Mermaid diagram to file
gitflow init # initialize git-flow
gitflow setup # detect IDE & generate rules
gitflow setup --ide cursor # force Cursor rules only
gitflow setup --ide copilot # force Copilot instructions only
IDE-specific rule file, IDE MCP config, .agents/skills/gitflow/SKILL.md
Zed / Neovim / JetBrains / Unknown
IDE-specific files if applicable, AGENTS.md, ~/.agents/skills/gitflow/SKILL.md
Cursor / VS Code / Copilot + Claude Code companion install: when the
primary IDE is Cursor, VS Code, or Copilot and Claude Code is detected in
the same environment (env vars CLAUDE_* / ANTHROPIC_*, or parent process
claude), gitflow setup also installs Claude Code artifacts as a companion:
CLAUDE.md and .claude/mcp.json. The skill is shared (single install under
.agents/skills/gitflow/SKILL.md). No flag is needed; the companion install
is fully automatic. To bypass, unset the Claude env vars before running
gitflow setup.
These files instruct the AI agent to run gitflow --json status before modifying any code, and the embedded skill is auto-updated if its content changes in newer gitflow binaries.
What AGENTS.md Is For
AGENTS.md is a repository-level instruction file for AI coding agents. It defines mandatory workflow rules (for example, gitflow pre-flight checks, branch routing, and safety constraints) that the agent should follow before making code changes.
gitflow setup generates AGENTS.md when an IDE/agent does not use a dedicated rules format as its primary instruction source, or when a generic fallback instruction file is needed.
IDEs/Agents That Use AGENTS.md
In this project, AGENTS.md is primarily used (or used as fallback) by these environments:
Zed
Neovim-based agent setups
JetBrains-based agent setups
Unknown or generic agent-compatible IDEs
For Cursor and VS Code Copilot, the primary files are .cursor/rules/gitflow-preflight.mdc and .github/copilot-instructions.md respectively, while AGENTS.md remains the compatibility fallback for other tools.
Copilot-Specific Notes
To ensure the embedded gitflow skill works in Copilot end-to-end:
Install gitflow binary and make sure it is in PATH.
Run gitflow setup --ide copilot in your repository root.
Verify these files exist:
.github/copilot-instructions.md
.vscode/mcp.json (contains "gitflow" server using gitflow serve)
.agents/skills/gitflow/SKILL.md
If gitflow is not in PATH when setup runs, MCP config still gets generated, but command execution will fail until PATH is fixed.
Embedded Skill
gitflow setup now installs the gitflow skill from the binary itself.
Project-local install for supported IDEs: .agents/skills/gitflow/SKILL.md
User-level fallback for unsupported IDEs: ~/.agents/skills/gitflow/SKILL.md
If the embedded skill content changes in a newer binary, gitflow setup updates the installed SKILL.md automatically.
Configuration
Create a .gitflow/config.json in your project root for custom settings:
If absent, the tool auto-detects common version files (package.json, pyproject.toml, Cargo.toml, etc.) and uses git tags for versioning.
Building
make build # build for current platform
make build-all # cross-compile linux/windows/macOS
make universal # create macOS universal binary with lipo
make test # run tests
make vet # run go vet
make release-local # build release artifacts locally (no publish — CI is the sole publisher)
make release-snapshot # goreleaser --snapshot, validates config without publishing
make install # install to a user-writable dir (no sudo needed)
Testing & Coverage
Coverage profiles generated by the Makefile are written into the test/ directory.
Run all tests and produce an aggregated coverage profile:
make cover
# writes `test/coverage.out`
Run tests for a single package and produce a package-specific profile:
make cover-package PKG=./internal/commands
# writes `test/commands.cov`
Keep test/ out of releases and CI artifacts; these files are intended for local inspection and CI coverage steps.
Release Pipeline
GitHub Actions is the sole publisher. Local make targets only build
artifacts into dist/; they never push to the GitHub Release. Pushing source
to a release/* or hotfix/* branch and finishing the branch produces the
v* tag, which triggers the workflow below.
test — runs go test ./... -race and enforces a per-package
coverage gate of ≥ 60% (target 80%). Each package is checked
independently; any package below the threshold fails the job with an
::error:: annotation naming the offending package.
release — runs GoReleaser (goreleaser release --clean) using the
existing .goreleaser.yml. Produces 4 OS/arch targets (linux/amd64,
linux/arm64, windows/amd64, darwin/arm64) + nfpms (.deb, .rpm, Arch)
for both Linux architectures + checksums.txt. Smoke-tests the
linux/amd64 binary. Extracts the ### TL;DR block from CHANGELOG.md
and uses it as the GitHub Release body. Uploads everything to a new
GitHub Release for the tag.
formula — bumps packaging/homebrew/gitflow.rb on main with the
new version + URL + SHA256 (read from the just-published checksums.txt).
When the HOMEBREW_TAP_GITHUB_TOKEN secret is configured on the repo,
the same bump is mirrored to novaemx/homebrew-tap/Formula/gitflow.rb.
All builds use -trimpath, -buildid=none, -ldflags="-s -w", and
-pgo=auto. PGO is a no-op until a default.pgo profile is committed to the
main package directory; once present, it activates automatically with no
config change (typical 5–14% speedup on hot paths).
Local validation (no publish)
# Lint the goreleaser config without producing artifacts
goreleaser check
# Build all 4 target archives into dist/ for inspection (no GitHub touch)
make release-snapshot
# Build a specific tag's artifacts into dist/ (no GitHub touch)
make release-local TAG=v0.6.8
