Skip to content
/ git-pr-manager Public

Production-ready git workflow automation for GitHub with Claude Code integration

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

littlebearapps/git-pr-manager

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

128 Commits
.github
.github
 
 
docs
docs
 
 
examples
examples
 
 
quickrefs
quickrefs
 
 
scripts/phase-2
scripts/phase-2
 
 
src
src
 
 
templates
templates
 
 
tests
tests
 
 
.eslintrc.json
.eslintrc.json
 
 
.gitignore
.gitignore
 
 
.gpm.example.yml
.gpm.example.yml
 
 
.gpm.yml
.gpm.yml
 
 
.mcp.json
.mcp.json
 
 
.npmignore
.npmignore
 
 
.releaserc.json
.releaserc.json
 
 
AUTO-FIX.md
AUTO-FIX.md
 
 
CHANGELOG.md
CHANGELOG.md
 
 
CLAUDE.md
CLAUDE.md
 
 
CODE_OF_CONDUCT.md
CODE_OF_CONDUCT.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
RENAME-VERIFICATION-REPORT.md
RENAME-VERIFICATION-REPORT.md
 
 
SECURITY.md
SECURITY.md
 
 
SESSION-SETUP.md
SESSION-SETUP.md
 
 
TEST-GAP-ANALYSIS.md
TEST-GAP-ANALYSIS.md
 
 
TEST-ISSUES-RESOLUTION.md
TEST-ISSUES-RESOLUTION.md
 
 
TEST-RUN-REPORT.md
TEST-RUN-REPORT.md
 
 
jest.config.js
jest.config.js
 
 
llms.txt
llms.txt
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
search-remaining-refs.sh
search-remaining-refs.sh
 
 
test-subprocess-issue.ts
test-subprocess-issue.ts
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

Git PR Manager (GPM)

Production-ready git workflow automation for GitHub with Claude Code integration. Streamlines feature development with intelligent CI polling, comprehensive error reporting, automated PR workflows, multi-language verification (Python, Node.js, Go, Rust), and automated release validation.

npm version CI Coverage Downloads License

⚡ TL;DR

Get started in 30 seconds:

# Install
npm install -g @littlebearapps/git-pr-manager

# Set GitHub token (get from: https://github.com/settings/tokens)
export GITHUB_TOKEN="ghp_your_token_here"

# Initialize
gpm init --interactive

# Use it!
gpm auto  # Full automated PR workflow: verify → security scan → PR → CI → merge

What it does: Automates your entire GitHub PR workflow—create feature branches, run security scans, create PRs, wait for CI checks, and auto-merge—all in one command. Supports Python, Node.js, Go, and Rust projects with automatic language detection.

Why gpm vs manual git workflows?

💡 Time Savings & Consistency

Manual PR workflows take 15-20 minutes per PR:

  • Run tests locally (forgot? CI fails after PR creation)
  • Run security scan (forgot? Secrets leak into history)
  • Create PR manually (copy-paste template, assign reviewers)
  • Check CI every 5 minutes (browser tab watching)
  • Click merge button when green

With gpm: gpm auto → 5-8 minutes, fully automated, never skip steps.

For teams: Standardized workflow = no more "I forgot to run tests" PRs.

For AI agents: Machine-readable JSON output (--json flag) on all commands. See AI Agent Integration Guide.

📖 Table of Contents

🔍 API Reference

Quick reference for all commands with JSON output schemas:

Command Purpose Key Flags JSON Output Schema
gpm auto Full automated workflow --draft, --no-merge, --skip-security, --skip-verify {prNumber, url, ciStatus, merged}
gpm ship Manual PR workflow --no-wait, --draft, --title, --template {prNumber, url, ciStatus}
gpm feature <name> Create feature branch --from <branch> {branch, created}
gpm checks <pr> CI status for PR --details, --files {total, passed, failed, pending, overallStatus}
gpm status Git/workflow status - {branch, clean, ahead, behind, hooks}
gpm security Security scanning - {passed, secretsFound, vulnerabilities}
gpm init Initialize config --template <preset>, --interactive {created, template, config}
gpm protect Branch protection --show, --preset <type>, --branch {enabled, requirements}
gpm setup Setup wizard --update, --method, --token, --skip-validation {success, method, location, configured}
gpm doctor System health check --pre-release, --json {token, tools, checks}
gpm install-hooks Install git hooks --post-commit, --force {installed, hooks}
gpm uninstall-hooks Remove git hooks - {removed}
gpm worktree list List worktrees - {worktrees: [{path, branch, commit}]}
gpm worktree prune Clean stale data --dry-run {pruned, count}
gpm verify | validate Pre-commit checks --skip-format, --skip-lint, --skip-test {passed, tasks: [{name, status, fixable}]}
gpm hooks status Git hooks status - {installed, hooks, config}
gpm check-update Check for updates --channel <next|latest>, --clear-cache {updateAvailable, currentVersion, latestVersion}
gpm docs View documentation --guide=<name> {guide, found, content}

Note: Add --json flag to any command for machine-readable output. All commands support --quiet, --silent, and --verbose flags for output control.

Complete schemas: See JSON Output Schemas Guide for detailed field descriptions and examples.

🎨 Common Workflows

Quick examples for the most common use cases:

# Daily feature development
gpm feature add-user-profile      # Start new feature
# ... make changes ...
gpm auto                          # Ship it (verify → security → PR → CI → merge)

# Code review
gpm checks 47                     # Check PR #47 status
gpm security                      # Run security scan

# Emergency hotfix
gpm feature hotfix-bug --from main  # Create hotfix from main
gpm ship --skip-verify --no-wait    # Fast-track PR

# Automation with JSON output
gpm auto --json                   # Machine-readable PR creation
gpm checks 47 --json              # Structured CI status
gpm doctor --json                 # System health check

📖 Complete Workflow Guides:

🎯 Who Should Use This

Ideal for: Solo developers, development teams, AI agents, and CI/CD engineers who want to automate GitHub workflows while maintaining control.

Perfect when you value:

  • ⚡ Speed: 60%+ time savings on PR workflows
  • 🔒 Security: Built-in secret scanning and vulnerability checks
  • 🤖 Automation: JSON output for scripting and AI agents
  • 🌍 Multi-language: Python, Node.js, Go, Rust with auto-detection

Not ideal for: Local-only git usage, GUI tool preferences, non-GitHub platforms (GitLab, Bitbucket)

Ready to try? Run gpm setup for interactive configuration, then gpm auto for your first automated PR workflow.

📖 Complete Guide: See docs/tutorials/getting-started.md for detailed scenarios, team size recommendations, and real-world case studies.

✨ What's New

Latest: v1.12.0 - AI Agent Hook Optimization (2025-11-24)

Git hooks now auto-detect AI agents and non-interactive environments:

  • ✅ TTY Detection: Hooks auto-skip in non-TTY mode (AI agents, pipes, redirects)
  • ✅ 70-80% Less Output: Cleaner command output for AI agents like Claude Code and Codex CLI
  • ✅ 100% Reliable JSON Parsing: No text pollution in automated workflows
  • ✅ 95% Faster Hook Execution: Immediate exit in automation contexts

Previous: v1.11.0 - TypeScript Type Safety + Branch Coverage (2025-11-24)

  • ✅ Strict TypeScript Types: Eliminated all 29 @typescript-eslint/no-explicit-any warnings
  • ✅ Enhanced Branch Coverage: Improved from 76.58% to 79.15% (+2.57%)
  • ✅ Zero TypeScript Warnings: Full ESLint compliance with strict type checking enabled
  • ✅ 1001 Tests: All passing with improved edge case coverage for doctor command and GitService worktree methods

Recent highlights:

  • ✅ v1.10.0: Codex CLI compatibility with standardized JSON output, auto-suppressed prompts/spinners for automation contexts
  • ✅ v1.9.0: Interactive setup wizard (gpm setup) with guided GitHub token configuration and multi-method secure storage
  • ✅ Release validation: Automated pre-release checks (gpm doctor --pre-release) ensure publish-ready state
  • ✅ Multi-language support: Python, Node.js, Go, Rust with automatic detection (v1.7.0)

📖 Full Release History: See CHANGELOG.md for complete version history and detailed release notes.

🚀 Quick Start

Installation

npm install -g @littlebearapps/git-pr-manager

Setup

Run Setup Wizard (Recommended)

The easiest way to get started is with the interactive setup wizard:

gpm setup

This wizard will:

  • ✅ Detect and verify required tools (git, node)
  • ✅ Check optional dependencies (gh CLI, detect-secrets, pip-audit)
  • ✅ Guide you through creating a GitHub token (with direct link and exact scopes)
  • ✅ Test your GitHub connection before storing
  • ✅ Help you choose secure storage method (ranked by security)
  • ✅ Provide copy-paste commands for immediate setup

Result: Complete setup in ~5 minutes with guided assistance.

Advanced options:

gpm setup github-token          # Configure GitHub token only
gpm setup --update              # Re-run setup for existing projects
gpm doctor                      # Check system requirements anytime

Manual Setup (Advanced Users)

Click to expand manual token setup options

If you prefer manual configuration or need custom setup:

1. Create GitHub Personal Access Token:

2. Store token (choose one method):

Option A: Shell profile (persistent, medium security)

echo 'export GITHUB_TOKEN="ghp_your_token_here"' >> ~/.zshrc
source ~/.zshrc

Option B: Session variable (temporary, testing only)

export GITHUB_TOKEN="ghp_your_token_here"

Option C: Project .env file (requires direnv)

echo 'GITHUB_TOKEN=ghp_your_token_here' >> .env
echo '.env' >> .gitignore  # CRITICAL: Prevent token leak

3. Verify:

echo $GITHUB_TOKEN  # Should show your token
gpm doctor          # Confirms setup

Why does gpm need a token?

💡 Understanding GitHub Tokens

gpm creates pull requests and checks CI status on your behalf. GitHub requires a token to prove you're authorized to perform these actions. Think of it like a password, but specifically for automation tools.

What can it do?

  • Create and merge pull requests
  • Check CI/CD status
  • Read repository information

What it CANNOT do:

  • Access other repositories (only repos you have access to)
  • Change account settings
  • Access private information outside of repository scope

Initialize Configuration

# Interactive setup wizard (recommended for first time)
gpm init --interactive

# Or use a preset template
gpm init --template standard  # Balanced settings (recommended)
gpm init --template strict    # Maximum protection
gpm init --template basic     # Minimal configuration

Basic Usage

# Start a new feature
gpm feature add-login-form

# ... make your changes ...

# Ship it! (automated workflow)
gpm auto

That's it! gpm auto will:

  1. ✅ Run verification checks (lint, test, typecheck)
  2. ✅ Run security scans (secrets, vulnerabilities)
  3. ✅ Push changes to GitHub
  4. ✅ Create pull request
  5. ✅ Wait for CI to pass
  6. ✅ Merge and cleanup

New to gpm? Check out our Complete Beginner's Guide (15 min) for step-by-step instructions with screenshots and examples.

📖 Commands

Quick command examples for the most common workflows:

# Full automated workflow (recommended)
gpm auto                        # Verify → Security → PR → CI → Merge

# Manual workflow
gpm feature <name>              # Create feature branch
gpm ship                        # Create PR and wait for CI
gpm ship --draft                # Create draft PR

# Pre-commit checks
gpm verify                      # Run format, lint, typecheck, test, build
gpm security                    # Scan secrets and vulnerabilities

# System utilities
gpm doctor                      # Check requirements & setup
gpm status                      # Show git/workflow status
gpm checks <pr>                 # Check CI status for PR

See API Reference above for complete command list with all flags and JSON schemas.

📖 Complete CLI Reference: See docs/CLI-REFERENCE.md for detailed documentation of all commands, options, examples, and exit codes.

❓ FAQ & Troubleshooting

Quick answers to common questions:

  • Token setup: Run gpm setup for interactive GitHub token configuration
  • System check: Run gpm doctor to verify all required and optional tools
  • Language detection: Auto-detects Python, Node.js, Go, Rust from project files
  • CI/CD integration: See GitHub Actions Integration Guide
  • JSON output: Add --json flag to any command for machine-readable output

📖 Complete FAQ: See docs/FAQ.md for detailed troubleshooting, common errors, and solutions.

🌍 Multi-Language Support

gpm verify automatically detects your project language and package manager, running appropriate verification commands for each ecosystem.

Supported Languages: Python, Node.js, Go, Rust

Quick Examples:

# Python project - auto-detects poetry, runs ruff, mypy, pytest
gpm verify

# Node.js project - auto-detects pnpm, runs eslint, tsc, jest
gpm verify

# Prefers Makefile targets when available
gpm verify  # Uses 'make lint', 'make test', etc.

Key Features:

  • Automatic language and package manager detection
  • Makefile integration with custom target mapping
  • Workspace detection (npm/yarn/pnpm workspaces)
  • Dependency installation support
  • Custom task ordering and skip options

📖 Complete Guide: See docs/guides/MULTI-LANGUAGE-SUPPORT.md for detailed examples, configuration options, and troubleshooting.

🔧 CI/CD & Automation

GitHub Actions - Automated PR validation and CI orchestration:

- name: Run security scan
  run: gpm security --json
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

AI Agents - Machine-readable JSON output for Claude Code, Aider, Cursor:

gpm auto --json          # Full PR workflow
gpm checks 123 --json    # Get structured CI status

📖 Complete Guides:

🎯 Key Features

Workflow Automation - Feature branch → PR → CI → Merge in one command (gpm auto) Enterprise Security - Secret detection, vulnerability scanning, language-aware scanners Intelligent CI Polling - Exponential backoff (5s → 30s), progress tracking, rich error reports Branch Protection - Validation, presets (basic/standard/strict), PR readiness checks Git Worktree Support - Conflict detection, smart parsing, enhanced error context Performance - API caching (40-60% fewer calls), request batching, rate limit handling Error Reporting - Classification, file extraction, suggested fixes, JSON output Auto-Fix - Intelligent linting/formatting/security fixes with verification and rollback (AUTO-FIX.md)

📋 Configuration

Quick setup: Run gpm init --template standard to generate a .gpm.yml config file with sensible defaults.

Templates: Choose from basic (minimal), standard (recommended), or strict (enforced verification and branch protection).

📖 Complete Reference: See docs/CONFIG.md for all configuration options, YAML examples, CLI flags, and environment variables.

System Health Check

Verify your setup and identify missing dependencies:

gpm doctor              # Check requirements & dependencies
gpm doctor --pre-release # Pre-release validation (7 checks)

Checks: GitHub token, required tools (git, node), optional tools (gh, detect-secrets, pip-audit)

Use when: After installation, troubleshooting errors, before publishing to npm

📖 Complete Guide: See docs/FAQ.md#what-tools-do-i-need-to-have-installed for detailed output examples and optional dependency explanations.

Environment Variables

Required:

export GITHUB_TOKEN="ghp_your_token_here"  # GitHub authentication
# Token needs 'repo' scope - Generate at https://github.com/settings/tokens/new

Optional:

export DEBUG=1                  # Enable verbose logging
export NO_UPDATE_NOTIFIER=1     # Disable update checks

Commands work without token: gpm status, gpm security, gpm init, gpm doctor, gpm install-hooks

📖 Complete Guide: See docs/CLI-REFERENCE.md#environment-variables for all variables and CI environment auto-detection.

🔧 Troubleshooting

Quick diagnostics if commands fail:

  1. Check GitHub token: gpm doctor - Validates token and system setup
  2. Common errors: GitHub token invalid → Run gpm setup github-token
  3. Environment issues: gpm: command not found → Add npm global bin to PATH

📖 Complete Troubleshooting Guide: See docs/FAQ.md for detailed error solutions, platform-specific issues, and common pitfalls.

🔧 Edge Cases & Recovery: See docs/guides/EDGE-CASES.md for failure scenarios (rate limiting, network errors, token expiration, merge conflicts) with step-by-step recovery procedures.

⚠️ Common Pitfalls

Things that trip up new users:

  1. Must commit before creating PR - ✅ Right: git add . && git commit → gpm auto
  2. Requires clean working tree - ✅ Commit or stash changes first
  3. Only works from feature branches - ✅ Create with gpm feature <name>
  4. GitHub token needs repo scope - ✅ Verify at https://github.com/settings/tokens

📖 Complete Troubleshooting Guide: See docs/FAQ.md#troubleshooting for detailed error solutions and common issues.

🏗️ Architecture

Clean TypeScript architecture with modular service layer:

  • Commands (src/commands/) - CLI command handlers (auto, ship, checks, security, etc.)
  • Services (src/services/) - Core business logic (GitHub API, Git operations, CI polling, auto-fix)
  • Utils (src/utils/) - Caching, error handling, logging, formatting

Built with: Octokit (GitHub API), simple-git (Git ops), Commander.js (CLI), TypeScript

📊 Performance Metrics

Real-world performance improvements measured across versions:

Metric v1.3.0 v1.4.0 Improvement
CI Wait Time (5 min checks) 10 min 6-7 min 30-40% ↓
PR Validation 800ms 380ms 40-50% ↓
Config Load (cached) 5ms 0.1ms 98% ↓
API Rate Limit Errors 5-10/day 0/day 100% ↓
API Calls per Ship 25-30 10-15 40-60% ↓

Test Environment

Hardware: MacBook Pro (M1, 16GB RAM) OS: macOS Sonoma 14.x Network: Fiber broadband (100 Mbps), latency to GitHub API ~20-30ms Repo Size: Medium project (~500 files, 50K LOC)

Methodology

  • Sample Size: Metrics averaged over 50+ real-world workflow runs
  • Measurement: Automated timing instrumentation + manual verification
  • CI Wait Time: Measured with 5-minute duration checks (typical test suite)
  • PR Validation: Time from gpm status invocation to completion
  • Config Load: File read + parse + validation time (with cache warm/cold)
  • API Calls: Counted via GitHub API response headers during gpm ship workflow
  • Variance: ±10-15% typical across runs (network-dependent)

Caveats

Results may vary based on:

  • Network latency: GitHub API response times vary by region and time of day
  • CI check duration: Longer test suites increase absolute wait time (but still benefit from adaptive polling)
  • Cache effectiveness: First runs are slower; subsequent runs benefit from LRU cache
  • Repository size: Larger repos may have slower git operations
  • Concurrent workflows: Multiple PRs in flight may affect API rate limits

Benchmarking Your Setup

Measure your own performance:

# Enable debug mode for detailed timing
DEBUG=1 gpm ship --no-wait

# Get JSON performance data
gpm ship --json | jq '.performance'

# Monitor API call count
gpm ship --verbose | grep "API calls"

Example output:

{
  "performance": {
    "totalDuration": 6734,
    "apiCalls": 12,
    "cacheHits": 8,
    "cacheHitRate": 0.67
  }
}

🧪 Testing

Production-ready test coverage:

  • 593 tests (565 unit + 28 integration) - ✅ All passing
  • 89.67% coverage (target: 80%) - ✅ Exceeded
npm test                  # Run all tests
npm run test:coverage     # With coverage report

📖 Complete Test Documentation: See docs/TESTS.md for detailed coverage breakdown, testing patterns, and contribution guidelines.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for development setup, guidelines, and CODE_OF_CONDUCT.md for community standards.

📚 Documentation

Quick Links:

Learning Paths:

  • Beginner: Tutorials (105 min total) → Basic Examples → FAQ
  • Advanced: Multi-Language Guide → GitHub Actions → AI Agent Integration
  • Contributors: Contributing Guide → Test Documentation → Architecture

📖 Complete Index: See docs/INDEX.md for comprehensive documentation navigation organized by user type, feature, and topic.

🗺️ Roadmap

Current Status: Production Ready ✅ (89.67% test coverage, 1.2k/month downloads)

Recent Achievements:

  • v1.9.x: Setup wizard, AI agent enhancements, shields.io badges
  • v1.8.x: Automated release validation, multi-language support (Python, Node.js, Go, Rust)
  • v1.7.x: Git hooks integration, worktree management, security enhancements

Planned Features (community-driven priority):

  • Enhanced AI integration (Claude Code workflows, smart commit messages)
  • Team collaboration (shared configs, organization policies)
  • Performance & scale (parallel CI polling, monorepo optimization)
  • Extended language support (Java, C#, PHP, Ruby)
  • Advanced security (SBOM, supply chain detection)

📖 Complete Roadmap: See docs/ROADMAP.md for detailed achievements, planned features, and how to contribute ideas.

📝 Changelog

Latest: v1.9.2 (2025-11-21) - Badge migration to shields.io + coverage/downloads badges

Recent releases: Setup wizard (v1.9.0), multi-language support (v1.7.0), automated release validation (v1.8.0), git hooks (v1.4.x)

📖 Complete Changelog: See CHANGELOG.md for detailed version history and release notes.

👥 Contributors

We're building git-pr-manager and looking for contributors to join us! Contributions of any kind are welcome.

Quick links:

Core Team: Nathan Schram (@nathanschram) - Creator & Maintainer | Little Bear Apps

Support the project: ⭐ Star the repo | 📢 Share with your team | 🐛 Report bugs | 📝 Write about gpm

📄 License

MIT License - Copyright (c) 2025 Nathan Schram / Little Bear Apps

See LICENSE for details.

🙏 Acknowledgments

Built with:

Made with ❤️ by Little Bear Apps

For support, please open an issue or contact nathan@littlebearapps.com.

About

Production-ready git workflow automation for GitHub with Claude Code integration

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 15

v1.12.0 Latest
Nov 24, 2025
+ 14 releases

Sponsor this project

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages