han-solo 🚀

AI-native Git workflow automation via Model Context Protocol (MCP) for Claude Code

han-solo is a powerful MCP server designed exclusively for Claude Code, streamlining Git workflows while maintaining clean, linear commit history. It provides structured validation, automated PR management, and seamless integration with GitHub.

Features

• 🤖 AI-Native Design: Built exclusively for Claude Code via Model Context Protocol (MCP)
• 🚀 One-Command Workflow: Ship entire features in a single MCP tool call
• 🛡️ Structured Validation: Pre/post-flight checks with JSON results (no UI dependencies)
• 🚫 Branch Reuse Prevention: Blocks reusing branch names after merge
• ✓ PR Conflict Detection: Ensures single PR per branch lifecycle
• 📈 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, CI monitoring, and merging
• 🔒 Safety First: Built-in safeguards prevent accidental commits to main
• 📍 Smart Status Line: Always-visible workflow status in Claude Code

Installation

MCP Server Setup

1. Clone and build the han-solo repository:

   git clone https://github.com/slamb2k/hansolo.git
   cd hansolo
   npm install
   npm run build

2. Configure Claude Code to load the MCP server: Add to your Claude Code MCP configuration file:

   {
     "mcpServers": {
       "hansolo": {
         "command": "node",
         "args": ["/path/to/hansolo/build/index.js"]
       }
     }
   }

3. Restart Claude Code to load the MCP tools

4. Initialize in your project using natural language:

   "Initialize han-solo in this project"

   Claude will invoke the hansolo_init tool automatically.

Quick Start

New to han-solo? Follow these steps to get started with Claude Code.

1. Initialize han-solo in your project

In Claude Code, ask:

Use hansolo_init to initialize han-solo in this project

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

2. (Optional) Set up GitHub authentication

# Option A: GitHub CLI (easiest)
gh auth login

# Option B: Personal access token
export GITHUB_TOKEN=ghp_your_token_here

3. Start a new feature workflow

In Claude Code, ask:

Use hansolo_launch to start a new feature for [your feature description]

This creates a new feature branch and starts tracking your workflow.

4. Make your changes

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

Use hansolo_status to check current workflow status

5. Ship your changes (One Command! 🚀)

In Claude Code, ask:

Use hansolo_ship to commit, push, create PR, and merge this feature

That's it! This single MCP tool call:

• ✅ Commits your changes
• ✅ Pushes to remote
• ✅ Creates or updates PR
• ✅ Waits for CI checks
• ✅ Auto-merges when ready
• ✅ Syncs main branch
• ✅ Deletes feature branches
• ✅ Completes session

Ready for your next feature! 🎉

Enable Status Line (Optional)

For always-visible workflow status in Claude Code:

Use hansolo_status_line with action "enable"

Core MCP Tools

All han-solo functionality is exposed through MCP tools that Claude Code can invoke.

hansolo_init

Initialize han-solo in your project. Creates configuration and session storage.

Input:

• scope (optional): Installation scope - "project" or "user" (default: "project")
• force (optional): Force reinitialization (default: false)

Returns: Structured result with success status and initialization details

hansolo_launch

Start a new feature workflow with automatic branch creation.

Input:

• branchName (optional): Specify branch name (auto-generated if omitted)
• description (optional): Add description for the feature
• force (optional): Launch even with uncommitted changes
• stashRef (optional): Git stash reference to restore after branch creation
• popStash (optional): Whether to pop the stash (default: true if stashRef provided)

Returns: SessionToolResult with pre/post-flight check results

hansolo_commit

Commit changes to the current feature branch.

Input:

• message (optional): Commit message (generated if omitted)
• stagedOnly (optional): If true, only commit staged files (default: false)

Returns: SessionToolResult with commit details

hansolo_ship

COMPLETE WORKFLOW: Complete the entire workflow automatically in a single command!

Ship handles everything: push → PR → CI wait → merge → cleanup

What it does:

1. Pushes to remote
2. Creates or updates GitHub PR
3. Waits for CI checks to pass (20 minute timeout)
4. Auto-merges PR with squash
5. Syncs local main branch
6. Deletes feature branches (local & remote)
7. Marks session as complete

Input:

• prDescription (optional): PR description (required for new PRs)
• push (optional): Push to remote (default: true)
• createPR (optional): Create pull request (default: true)
• merge (optional): Merge PR after CI passes (default: true)
• force (optional): Override safety checks
• yes (optional): Skip confirmations
• stagedOnly (optional): Only commit staged files when committing changes

Returns: GitHubToolResult with PR number, URL, and merge status

hansolo_sessions

List and manage active workflow sessions.

Input:

• all (optional): Show all sessions including completed
• verbose (optional): Detailed session information
• cleanup (optional): Remove expired sessions

Returns: QueryToolResult with session list

hansolo_swap

Switch between active workflow sessions.

Input:

• branchName: Branch to swap to (required)
• force (optional): Force swap with uncommitted changes
• stash (optional): Stash changes before swapping

Returns: SessionToolResult with swap details

hansolo_abort

Cancel an active workflow session.

Input:

• branchName (optional): Specify branch to abort (current if omitted)
• deleteBranch (optional): Delete the branch after aborting
• force (optional): Force abort
• yes (optional): Skip confirmation

Returns: SessionToolResult with abort details

hansolo_status

Show current workflow status and session information.

Input: None required

Returns: QueryToolResult with current status

hansolo_status_line

Manage Claude Code status line display.

Input:

• action: Action to perform - "enable", "disable", "update", or "show" (required)
• format (optional): Custom format string (e.g., "{icon} {branch} {state}")
• showBranchInfo (optional): Show branch name in status line
• showSessionInfo (optional): Show session ID in status line
• showStateInfo (optional): Show workflow state in status line

Returns: QueryToolResult with status line configuration

hansolo_hotfix

Create emergency hotfix workflow.

Input:

• issue (optional): Issue number or description
• severity (optional): Severity level - "critical", "high", or "medium"
• force (optional): Force operations
• skipTests (optional): Skip running tests
• skipReview (optional): Skip code review
• autoMerge (optional): Automatically merge when checks pass
• yes (optional): Skip confirmations

Returns: SessionToolResult with hotfix details

Structured Results

All MCP tools return structured JSON results for programmatic handling by Claude Code:

SessionToolResult

{
  success: boolean;
  branchName?: string;
  state?: string;
  preFlightChecks?: CheckResult[];
  postFlightVerifications?: CheckResult[];
  errors?: string[];
  warnings?: string[];
  nextSteps?: string[];
}

GitHubToolResult

{
  success: boolean;
  prNumber?: number;
  prUrl?: string;
  merged?: boolean;
  preFlightChecks?: CheckResult[];
  postFlightVerifications?: CheckResult[];
  errors?: string[];
  warnings?: string[];
}

QueryToolResult

{
  success: boolean;
  data: Record<string, unknown>;
  message?: string;
  errors?: string[];
  warnings?: string[];
}

Pre-Flight and Post-Flight Checks

Every MCP tool includes comprehensive validation with structured results:

Pre-Flight Checks (before execution):

• Validates prerequisites are met
• Returns structured check results
• Provides actionable error messages
• Can be overridden with force flag

Post-Flight Verifications (after execution):

• Confirms expected state was achieved
• Verifies all operations completed
• Identifies any issues that occurred
• Returns detailed verification results

Check Result Structure:

{
  name: string;
  passed: boolean;
  message: string;
  severity: 'error' | 'warning' | 'info';
  details?: {
    expected?: any;
    actual?: any;
    suggestion?: string;
  };
}

See docs/guides/validation.md for complete documentation.

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

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.

Features

• Automatic PR creation with generated descriptions
• CI check monitoring with configurable timeout
• Review status tracking
• Squash merge support
• Automatic branch cleanup

Status Line Integration

The status line provides at-a-glance workflow information directly in Claude Code:

[han-solo] 💻 0c2a20a7 | feature/my-feature | BRANCH_READY

Status Line Components:

• Session ID: Short identifier for current session
• Branch Name: Current feature branch
• State: Workflow state (BRANCH_READY, PUSHED, etc.)

Managing the Status Line:

Use hansolo_status_line with action "enable"
Use hansolo_status_line with action "disable"
Use hansolo_status_line with action "show"
Use hansolo_status_line with action "update" and showBranchInfo true

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
preferences:
  defaultBranchPrefix: feature/
  autoCleanup: true
  prTemplate:
    footer: "🤖 Generated with han-solo"

Architecture

han-solo follows a pure MCP architecture:

┌─────────────────────────────────┐
│         Claude Code             │
│    (MCP Client - AI Agent)      │
└─────────────────────────────────┘
                ↓ JSON-RPC
┌─────────────────────────────────┐
│       MCP Server                │
│    (HanSoloMCPServer)           │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│       MCP Tools Layer           │
│  (LaunchTool, ShipTool, etc.)   │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│  Validation Services Layer      │
│  (Pre/Post-Flight Checks)       │
└─────────────────────────────────┘
                ↓
┌─────────────────────────────────┐
│     Core 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

Testing the MCP Server

# Build MCP server
npm run build:mcp

# Start MCP server for testing
npm run mcp:start

# Run MCP tests
npm run test:mcp

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

# Unit tests only
npm run test:unit

# Integration tests only
npm run test:integration

# MCP server tests only
npm run test:mcp

Documentation

Getting Started

• docs/guides/quickstart.md - Get up and running in 5 minutes
• docs/guides/installation.md - Detailed installation instructions
• docs/guides/usage.md - Practical examples and real-world scenarios

Reference

• docs/guides/mcp-tools-reference.md - Complete MCP tool reference
• docs/dev/system/configuration.md - Configuration options
• docs/dev/system/pre-flight-checks.md - Pre/post-flight checks documentation

Advanced

• docs/dev/system/mcp-architecture.md - MCP architecture overview
• docs/dev/system/mcp-tools.md - MCP tools implementation details
• docs/dev/plans/phase3-pure-mcp-architecture.md - MCP-only design philosophy

Migration

• docs/guides/migration-from-cli.md - Migrating from CLI-based versions (v1.x)

Contributing

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

1. Fork the repository
2. Start a new workflow (Use hansolo_launch via Claude Code)
3. Make your changes
4. Add tests for new functionality
5. Run tests and linting
6. Ship your changes (Use hansolo_ship via Claude Code)
7. 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 v2.0 - AI-native Git workflow automation for Claude Code 🤖