hansolo-cli

han-solo 🚀

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.

Features

• Linear History Enforcement: Ensures all merges result in clean, linear commit history
• Session Management: Track multiple concurrent workflows with isolated sessions
• State Machine Control: Deterministic workflow states prevent invalid operations
• GitHub Integration: Automatic PR creation, review tracking, and merging
• MCP Server: Native Claude Code integration for AI-assisted workflows
• Visual Feedback: Rich terminal UI with progress indicators and status displays
• Safety First: Built-in safeguards prevent accidental commits to main

Installation

Global Installation (Recommended)

npm install -g @hansolo/cli

Project-level Installation

npm install --save-dev @hansolo/cli

Quick Start

1. Initialize han-solo in your project

hansolo init

This creates a .hansolo directory with configuration and session storage.

2. Start a new feature workflow

hansolo launch --branch feature/my-awesome-feature

3. Make your changes

Work on your feature as normal. han-solo tracks your session automatically.

4. Ship your changes

# Commit changes
hansolo ship

# Push to remote
hansolo ship --push

# Create PR
hansolo ship --create-pr

# Merge after approval
hansolo ship --merge

Core Commands

hansolo init

Initialize han-solo in your project. Creates configuration and installs Git hooks.

Options:

• --scope [project|user] - Installation scope (default: project)
• --force - Force reinitialization

hansolo launch

Start 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 changes

hansolo ship

Complete workflow stages from commit to merge.

Options:

• --message <msg> - Commit message
• --push - Push changes to remote
• --create-pr - Create GitHub pull request
• --merge - Merge PR to main (after approval)
• --force - Force operations
• --yes - Skip confirmations

hansolo sessions

List and manage active workflow sessions.

Options:

• --all - Show all sessions including completed
• --verbose - Detailed session information
• --cleanup - Remove expired sessions

hansolo swap

Switch between active workflow sessions.

Usage:

hansolo swap [branch-name]

Options:

• --force - Force swap with uncommitted changes
• --stash - Stash changes before swapping

hansolo abort

Cancel 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 workflows

hansolo status

Show current workflow status and session information.

Workflow States

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.

GitHub Integration

han-solo integrates with GitHub API for automated PR management.

Setup

Set your GitHub token as an environment variable:

export GITHUB_TOKEN=your_github_token
# or
export GH_TOKEN=your_github_token

Features

• Automatic PR creation with generated descriptions
• Review status tracking
• Check suite monitoring
• Squash merge support
• Automatic branch cleanup

MCP Server (Claude Code Integration)

han-solo includes an MCP server for seamless Claude Code integration.

Running the MCP Server

hansolo-mcp

Available MCP Tools

• hansolo_init - Initialize han-solo
• hansolo_launch - Start new workflow
• hansolo_sessions - List sessions
• hansolo_swap - Switch sessions
• hansolo_abort - Cancel workflow
• hansolo_ship - Complete workflow
• hansolo_status - Show status

Session Management

Sessions are stored in .hansolo/sessions/ with automatic persistence:

• Each workflow creates a unique session ID
• Sessions track state history and transitions
• Automatic lock management prevents conflicts
• Sessions expire after 30 days of inactivity

Configuration

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

Architecture

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)       │
└─────────────────────────────────┘

Development

Building from Source

# 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

Running Locally

# Link for local development
npm link

# Now use globally
hansolo init

Testing

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

Documentation

• Installation Guide - Detailed installation instructions
• API Documentation - Complete API reference
• Contributing Guide - How to contribute to han-solo
• Changelog - Version history and changes
• Examples - Usage examples and workflows
• Man Page - Unix manual page

Shell Completions

han-solo provides shell completions for enhanced CLI experience:

• Bash: source completions/hansolo.bash
• ZSH: source completions/hansolo.zsh
• Fish: Copy to ~/.config/fish/completions/

Git Hooks

Install Git hooks to enforce han-solo workflows:

sh hooks/install.sh

Available hooks:

• pre-commit: Prevents direct commits to protected branches
• pre-push: Validates workflow state before pushing
• commit-msg: Enforces conventional commit messages

Docker Support

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

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

• Fork the repository
• Create a feature branch (hansolo launch --branch feature/your-feature)
• Make your changes
• Add tests for new functionality
• Run tests and linting
• Ship your changes (hansolo ship)
• Create a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Built with TypeScript
• MCP integration via @modelcontextprotocol/sdk
• GitHub API via @octokit/rest
• Git operations via simple-git

han-solo - May your commits be linear and your conflicts be few 🚀