hansolo-cli
Advanced tools
Git workflow automation tool that enforces linear history and prevents merge conflicts
Git workflow automation tool that enforces linear history and prevents merge conflicts
han-solo is a powerful CLI tool designed to streamline Git workflows while maintaining clean, linear commit history. It integrates with Claude Code through MCP (Model Context Protocol) and GitHub API for seamless PR management.
npm install -g @hansolo/cli
npm install --save-dev @hansolo/cli
New to han-solo? Check out the Quick Start Guide for a detailed walkthrough, or follow the steps below to get started immediately.
cd your-project
hansolo init
This creates a .hansolo directory with configuration and session storage. If Claude Code is detected, it automatically sets up MCP integration.
# Option A: GitHub CLI (easiest)
gh auth login
# Option B: Personal access token
export GITHUB_TOKEN=ghp_your_token_here
hansolo launch
This creates a new feature branch and starts tracking your workflow.
Work on your feature as normal. han-solo tracks your session automatically.
# Check status anytime
hansolo status
hansolo ship
That's it! This single command:
Ready for your next feature! 🎉
Using Claude Code? After hansolo init, enable the status line for always-visible workflow status:
/hansolo:status-line enable
For detailed examples and advanced workflows, see the Usage Guide.
hansolo initInitialize han-solo in your project. Creates configuration and installs Git hooks.
Options:
--scope [project|user] - Installation scope (default: project)--force - Force reinitializationhansolo launchStart a new feature workflow with automatic branch creation.
Options:
--branch <name> - Specify branch name (auto-generated if omitted)--description <desc> - Add description for the feature--force - Launch even with uncommitted changeshansolo shipNEW IN V2: Complete the entire workflow automatically in a single command!
Ship now handles everything: commit → push → PR → CI wait → merge → cleanup
What it does:
Options:
--message <msg> - Custom commit message--force - Override safety checks--yes - Skip confirmations (for automation)Example:
# Ship everything at once
hansolo ship
# With custom commit message
hansolo ship --message "feat: add user authentication"
# Skip confirmations for CI/CD
hansolo ship --yes
hansolo sessionsList and manage active workflow sessions.
Options:
--all - Show all sessions including completed--verbose - Detailed session information--cleanup - Remove expired sessionshansolo swapSwitch between active workflow sessions.
Usage:
hansolo swap [branch-name]
Options:
--force - Force swap with uncommitted changes--stash - Stash changes before swappinghansolo abortCancel an active workflow session.
Options:
--branch <name> - Specify branch to abort (current if omitted)--delete-branch - Delete the branch after aborting--force - Force abort--yes - Skip confirmation--all - Abort all active workflowshansolo statusShow current workflow status and session information.
hansolo cleanupClean up completed sessions, merged branches, and sync main with remote.
Critical: Run this after PRs are merged on GitHub to ensure local main is synced and feature branches are removed.
Usage:
hansolo cleanup
Options:
--dry-run - Show what would be cleaned up without making changes--force / -f - Skip confirmation prompts--all - Clean up everything including old audit logs--sessions-only - Only clean up sessions, keep branches--branches-only - Only clean up branches, keep sessions--days <N> - Clean up sessions completed N+ days ago (default: 30)--no-sync - Skip syncing main branch with remoteWhat it does:
--all) Removes old audit entriesWhen to run:
Every command now includes comprehensive validation:
Pre-Flight Checks (before execution):
🔍 Pre-Flight Checks (5/5 passed)
✓ On main/master branch: main
✓ Working directory clean
✓ Main up to date with origin
✓ No existing session
✓ Branch name available: feature/my-feature
✓ All checks passed (5/5)
Post-Flight Verifications (after execution):
✅ Post-Flight Verification (5/5 passed)
✓ Session created: ID: abc12345...
✓ Feature branch created: feature/my-feature
✓ Branch checked out: feature/my-feature
✓ Session state: BRANCH_READY
✓ No uncommitted changes
Benefits:
See PRE-FLIGHT-CHECKS.md for complete documentation.
Han-solo now prevents branch name reuse after merge:
| Scenario | Action |
|---|---|
| Branch merged & deleted | BLOCKED - Name retired |
| Branch merged, deleted, recreated | BLOCKED - Critical error |
| Branch aborted (never merged) | ALLOWED - Safe to reuse |
| Adding commits after merge | ALLOWED - Creates new PR |
Example:
hansolo launch "add-auth"
# ... work, ship, merge ...
hansolo launch "add-auth"
# ✗ Branch name available: Previously used for PR #15
# Branch names cannot be reused after merge
# Suggestion: feature/add-auth-v2
Enforces single PR per branch lifecycle:
| Scenario | Action |
|---|---|
| Multiple open PRs | BLOCKED - Manual fix needed |
| Single open PR | UPDATES existing PR |
| Previous PR merged | CREATES new PR |
| No PR exists | CREATES new PR |
All commands now display professional banners:
╔═══════════════════════════════════════════╗
║ 🚀 LAUNCHING WORKFLOW 🚀 ║
╚═══════════════════════════════════════════╝
Consistent branding across:
See MIGRATION-V2.md for complete migration guide.
Key Changes:
hansolo ship now does everything automatically (no more flags)han-solo uses a deterministic state machine to manage workflows:
INIT → BRANCH_READY → CHANGES_COMMITTED → PUSHED →
PR_CREATED → WAITING_APPROVAL → MERGED → COMPLETE
Each state has specific allowed transitions and validations to ensure workflow integrity.
han-solo integrates with GitHub API for automated PR management.
Option 1: Use GitHub CLI (Recommended for local development)
gh auth login
Option 2: Set environment variable (For CI/CD)
export GITHUB_TOKEN=your_github_token
# or
export GH_TOKEN=your_github_token
han-solo automatically detects and uses gh CLI authentication if available, so explicit token setup is often unnecessary for local development.
han-solo includes an MCP server for seamless Claude Code integration.
Initialize han-solo in your project:
hansolo init
This automatically configures the MCP server in Claude Code.
Enable the Status Line (optional but recommended):
/hansolo:status-line enable
Start using han-solo via Claude Code:
/hansolo:launch
/hansolo:ship
/hansolo:status
All han-solo commands are available through Claude Code's slash command interface:
| Command | Description |
|---|---|
/hansolo:init | Initialize han-solo in your project |
/hansolo:launch | Start a new feature workflow |
/hansolo:ship | Complete and merge your feature |
/hansolo:status | Show current workflow status |
/hansolo:sessions | List all active sessions |
/hansolo:swap | Switch between sessions |
/hansolo:abort | Cancel current workflow |
/hansolo:status-line | Manage Claude Code status line |
The status line provides at-a-glance workflow information directly in Claude Code:
[han-solo] ✏️ 0c2a20a7 | feature/my-feature | BRANCH_READY | 45000/200000 ██░░░░░░░░ 22%
Status Line Components:
Managing the Status Line:
# Enable status line
/hansolo:status-line enable
# Disable status line
/hansolo:status-line disable
# Show current status
/hansolo:status-line show
# Update configuration
/hansolo:status-line update --show-branch-info true
Sessions are stored in .hansolo/sessions/ with automatic persistence:
Configuration is stored in .hansolo/config.yaml:
initialized: true
scope: project
gitPlatform:
type: github
owner: your-org
repo: your-repo
components:
mpcServer: true
statusLines: true
gitHooks: true
preferences:
defaultBranchPrefix: feature/
autoCleanup: true
confirmBeforePush: true
colorOutput: true
verboseLogging: false
han-solo follows a layered architecture:
┌─────────────────────────────────┐
│ Claude Code │
│ (via MCP) │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ CLI Interface │
│ (Commands & Options) │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ State Machine Layer │
│ (Workflow Control & Rules) │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ Services Layer │
│ (Git, GitHub, Sessions, Config) │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ Persistence Layer │
│ (File System & Git Repo) │
└─────────────────────────────────┘
# Clone the repository
git clone https://github.com/slamb2k/hansolo.git
cd hansolo
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run tests
npm test
# Run with coverage
npm run test:coverage
# Link for local development
npm link
# Now use globally
hansolo init
han-solo includes comprehensive tests for all components:
# Run all tests
npm test
# Watch mode
npm run test:watch
# Coverage report
npm run test:coverage
han-solo provides shell completions for enhanced CLI experience:
source completions/hansolo.bashsource completions/hansolo.zsh~/.config/fish/completions/Install Git hooks to enforce han-solo workflows:
sh hooks/install.sh
Available hooks:
Run han-solo in a container:
# Build image
docker build -t hansolo .
# Run container
docker run -it --rm -v $(pwd):/workspace hansolo
# Using docker-compose
docker-compose run hansolo
Contributions are welcome! Please see our Contributing Guide for details.
hansolo launch --branch feature/your-feature)hansolo ship)MIT License - see LICENSE file for details
han-solo - May your commits be linear and your conflicts be few 🚀
FAQs
Git workflow automation tool that enforces linear history and prevents merge conflicts
We found that hansolo-cli demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.
Security News
An OpenCode user faced harassment after reporting a free AI usage loophole, drawing a bitter backlash in a GitHub thread that has since been deleted.
Threat Research
/Security News
319 browser extensions installed by 13.4 million users hijack searches, capture queries, and collect referral payments from Yahoo and Bing.