managing-forks

mcfearsome/fork-yeah

Manages parallel conversation branches using git worktrees. Use when you want to explore multiple solution approaches simultaneously, need to try different implementations, or want to checkpoint your current conversation state before branching into alternative paths.

0 stars

0 forks

Shell

4 views

View on GitHub Add to Favorites

SKILL.md

name: managing-forks description: Manages parallel conversation branches using git worktrees. Use when you want to explore multiple solution approaches simultaneously, need to try different implementations, or want to checkpoint your current conversation state before branching into alternative paths.

Managing Forks - Conversation Branching for Claude Code

This skill enables you to create and manage parallel conversation branches (forks) using git worktrees. Each fork is an independent workspace where you can explore different approaches to solving a problem.

When to Use This Skill

Use fork management when:

The user wants to try multiple implementation approaches in parallel
You need to explore different solutions without losing your current progress
The user asks to "fork" the conversation or try alternatives
Working on a feature and want to experiment with different designs
The user wants to checkpoint the current state before making major changes

Core Commands

Creating Forks

Basic Fork Creation:

src/fork_create.sh <number>

Creates N parallel fork branches from the current conversation checkpoint.

Example:

src/fork_create.sh 3

Creates 3 parallel branches, each with its own git worktree.

Fork with Target Branch:

src/fork_create.sh <number> --target <branch-name>

Creates N forks that all target a specific branch (useful for feature development).

Example:

src/fork_create.sh 3 --target feature-auth

Creates 3 forks from and targeting the feature-auth branch. All forks will merge back to this branch.

Listing Forks

src/fork_list.sh

Shows all active fork branches with their metadata, creation time, status, and worktree paths.

Viewing Fork Hierarchy

src/fork_tree.sh

Displays a visual tree representation of all forks and their parent-child relationships. Useful for understanding nested fork structures.

Switching Between Forks

src/fork_switch.sh <fork-id>

Switches the working environment to a different fork branch.

Example:

src/fork_switch.sh fork-1730678901-a1b2c3d4-2

Checking Fork Status

src/fork_status.sh

Shows the current fork's status, including git status, worktree information, and fork metadata.

Merging Forks

src/fork_merge.sh <source-fork-id>

Merges changes from another fork branch into the current branch.

Example:

src/fork_merge.sh fork-1730678901-a1b2c3d4-1

Deleting Forks

src/fork_delete.sh <fork-id>

Deletes a fork branch, its worktree, and associated metadata. Prompts for confirmation.

Example:

src/fork_delete.sh fork-1730678901-a1b2c3d4-3

Workflow Examples

Example 1: Exploring Multiple Implementation Approaches

User asks: "I want to try implementing this feature using both REST and GraphQL approaches"

Response workflow:

Create 2 forks: src/fork_create.sh 2 --target feature-api
In fork-1: Implement using REST
In fork-2: Implement using GraphQL
User evaluates both approaches
Merge the preferred approach back to feature-api

Example 2: Trying Different Design Patterns

User asks: "Let's explore both MVC and Clean Architecture for this"

Response workflow:

Ensure current work is committed
Create 2 forks: src/fork_create.sh 2 --target feature-refactor
Switch to fork-1: Implement MVC pattern
Switch to fork-2: Implement Clean Architecture
User compares both implementations
Merge chosen pattern back

Example 3: Nested Forks for Sub-Experiments

User asks: "In the GraphQL approach, let's try two different schema designs"

Response workflow:

Switch to the GraphQL fork
Create nested forks: src/fork_create.sh 2 --target graphql-schema
Implement different schemas in each nested fork
Merge best schema back to GraphQL fork
Eventually merge GraphQL fork to main feature branch

Best Practices

Before Creating Forks

Commit current work: Ensure git working directory is clean
```
git add . && git commit -m "checkpoint before forking"
```
Check you're in a git repository:
```
git status
```
Plan your forks: Think about how many parallel approaches you need

During Fork Work

Stay organized: Use descriptive commit messages in each fork
Document differences: Note why each approach differs
Test independently: Each fork should be tested on its own
Use fork status: Regularly check src/fork_status.sh to see where you are

After Fork Work

Evaluate results: Compare implementations across forks
Merge carefully: Use src/fork_merge.sh to combine best elements
Clean up: Delete unused forks with src/fork_delete.sh
Document decisions: Note why you chose one approach over another

Technical Details

What Happens When You Create a Fork

Git worktree creation: Each fork gets an isolated git worktree
Checkpoint saving: Current conversation state is saved to JSON
Branch creation: New git branch created for the fork
Metadata storage: Fork information stored in ~/.claude-code/forks/
Terminal session: If tmux is available, creates dedicated session

Fork Data Structure

~/.claude-code/forks/
├── fork-xxx-1/
│   ├── checkpoint.json     # Conversation state
│   ├── metadata.json       # Fork metadata
│   ├── worktree/          # Git worktree
│   └── launch.sh          # Launcher script
├── fork-xxx-2/
│   └── ...
└── .fork-groups.json      # Fork group relationships

Metadata Fields

Each fork stores:

fork_id: Unique identifier
parent_id: Parent fork (for nested forks)
target_branch: Target branch for merging (if specified)
branch_number: Position in fork group
total_branches: Total forks in group
worktree_path: Path to git worktree
status: active/archived
created_at: ISO timestamp

Error Handling

Common Issues

"Not in a git repository"

Solution: Navigate to a git repository before creating forks

"Worktree already exists"

Solution: Run git worktree prune to clean up stale worktrees

"Fork not found"

Solution: Run src/fork_list.sh to see available forks

"Cannot create worktree"

Solution: Ensure uncommitted changes are committed or stashed

Recovery

If forks become corrupted:

List all worktrees: git worktree list
Prune stale worktrees: git worktree prune
Clean fork data: rm -rf ~/.claude-code/forks/<bad-fork-id>

Limitations

Maximum 10 forks can be created at once (configurable)
Fork IDs are auto-generated and not human-readable
Worktrees must be on the same filesystem
Each fork requires disk space for its worktree

Integration with Terminal Multiplexing

tmux Mode (Recommended)

When tmux is installed:

Each fork gets a dedicated tmux session
Easy switching with tmux attach -t fork-<id>
Multiple panes can be created in each session

Fallback Modes

When tmux is not available:

macOS: Generates iTerm2/Terminal.app launcher scripts
Linux: Creates shell launcher scripts
Basic: Simple directory switching

Configuration

User configuration is stored in ~/.config/fork-yeah/config.yaml:

terminal:
  mode: auto  # auto, tmux, macos, linux, basic

fork:
  max_forks: 10
  auto_checkpoint: true

display:
  use_colors: true
  tree_ascii: true

Tips for Effective Fork Usage

Communicate clearly: Tell the user which fork you're working in
Use target branches: Always specify --target for feature work
Keep forks focused: Each fork should explore one specific approach
Document as you go: Add commit messages explaining your choices
Merge incrementally: Don't wait until the end to merge good ideas
Visualize often: Use src/fork_tree.sh to stay oriented

README

🍴 fork-yeah

A Claude Code plugin for branching conversation paths

Fork-yeah enables you to create parallel branches of your Claude Code conversations, allowing you to explore different approaches while "saving your spot." Think of it as git branches for your AI conversations.

Features

Parallel Conversation Paths: Create N parallel branches from any point in your conversation
Git Worktrees: Each fork gets its own isolated git worktree
State Checkpointing: Saves complete conversation state at fork points
Terminal Multiplexing: Seamless integration with tmux for managing multiple forks
Nested Forks: Support for creating forks within fork branches
Visual Fork Tree: See your fork hierarchy at a glance
Cross-Platform: Works on Linux, macOS, and Windows (WSL)

Part of the mcfearsome marketplace - Quality plugins for Claude Code See MARKETPLACE.md for more plugins and marketplace information.

Quick Start

Installation

# Clone the repository
git clone https://github.com/mcfearsome/fork-yeah
cd fork-yeah

# Run setup
./setup.sh

The setup script will:

Check for required dependencies (git, python3, jq)
Optionally install tmux for the best experience
Create necessary directories
Link the plugin to Claude Code

Basic Usage

Inside Claude Code:

# Create 3 parallel branches from current conversation
/fork create 3

# List all your forks
/fork list

# View fork hierarchy
/fork tree

# Switch to a specific fork
/fork switch fork-1234567890-abc123-2

# Check current fork status
/fork status

# Merge changes from another fork
/fork merge fork-1234567890-abc123-1

# Delete a fork
/fork delete fork-1234567890-abc123-3

How It Works

The Fork Workflow

Checkpoint: When you create a fork, fork-yeah saves the current conversation state and git commit
Branch: Creates N git branches from that commit point
Worktree: Sets up isolated git worktrees for each fork
Launch: Spawns terminal sessions (tmux panes/windows) for each fork
Work: Each fork can evolve independently
Merge: Optionally merge successful approaches back together

Example Scenario

# You're working on a feature and want to try two approaches

# Save your current work
git add . && git commit -m "baseline before fork"

# Create two parallel branches
/fork create 2

# This creates:
# - fork-xxx-1: Try approach A
# - fork-xxx-2: Try approach B

# Work on each approach independently
# Then merge the better one back to main

Commands Reference

`/fork create <number> [--target <branch_name>]`

Create N parallel fork branches.

Arguments:

number: Number of branches (1-10)
--target <branch_name> (optional): Target branch all forks will merge to

Examples:

# Create 3 parallel branches from current point
/fork create 3

# Create 3 branches targeting feature-auth branch
/fork create 3 --target feature-auth

# All forks will be created from and merge back to feature-auth

What it does:

Captures current conversation state
Creates or checks out target branch (if --target specified)
Creates git branches from current commit
Sets up worktrees for each fork
Launches terminal sessions (if tmux available)
Stores target branch info for future merges

Target Branch Benefits:

All forks start from the same named branch
Makes it clear where work should merge back to
Useful for feature development with multiple approaches
Target branch is shown in fork metadata

`/fork list`

List all active fork branches.

Output:

Fork ID
Creation time
Status
Worktree path
Branch number

`/fork switch <fork_id>`

Switch to a different fork branch.

Arguments:

fork_id: ID of fork to switch to

Example:

/fork switch fork-1730678901-a1b2c3d4-2

What it does:

Changes to fork's worktree directory
Attaches to tmux session (if using tmux)
Updates shell environment

`/fork tree`

Visualize fork hierarchy as a tree structure.

Output:

ASCII tree showing fork relationships
Parent-child connections
Fork metadata

`/fork status`

Show status of current fork and conversation state.

Output:

Current fork (if in one)
Fork details
Git status
Worktree information

`/fork merge <fork_id>`

Merge changes from another fork branch.

Arguments:

fork_id: Source fork to merge from

Example:

/fork merge fork-1730678901-a1b2c3d4-1

`/fork delete <fork_id>`

Delete a fork and its worktree.

Arguments:

fork_id: Fork to delete

Example:

/fork delete fork-1730678901-a1b2c3d4-3

What it does:

Kills associated tmux session
Removes git worktree
Deletes git branch
Cleans up fork data

Terminal Modes

Fork-yeah adapts to your environment:

tmux Mode (Recommended)

When tmux is installed:

Creates dedicated sessions for fork groups
Uses panes/windows for each fork
Seamless switching between forks
Full multiplexing capabilities

Fallback Modes

When tmux is not available:

macOS: Generates iTerm2/Terminal.app launchers
Linux: Creates shell launcher scripts
Basic: Simple directory switching

Configuration

Edit ~/.config/fork-yeah/config.yaml to customize:

# Terminal mode: auto, tmux, macos, linux, basic
terminal:
  mode: auto

# Fork creation settings
fork:
  max_forks: 10
  auto_checkpoint: true
  confirm_multiple: true

# Display settings
display:
  use_colors: true
  tree_ascii: true
  date_format: iso

File Structure

~/.claude-code/forks/          # Fork data directory
├── fork-xxx-1/
│   ├── checkpoint.json        # Conversation state
│   ├── metadata.json          # Fork metadata
│   ├── worktree/              # Git worktree
│   └── launch.sh              # Launcher script
├── fork-xxx-2/
│   └── ...
└── .fork-groups.json          # Fork group relationships

~/.config/fork-yeah/           # Configuration
├── config.yaml                # User config
└── tmux.conf                  # tmux settings

How the Plugin Works

fork-yeah integrates with Claude Code through two mechanisms:

1. Slash Commands (`commands/` directory)

User-invoked commands that you type explicitly:

/fork create 3 - Create forks
/fork list - List all forks
/fork switch <id> - Switch forks
/fork tree - View hierarchy
/fork status - Check status
/fork merge <id> - Merge forks
/fork delete <id> - Delete forks

These appear in Claude Code's /help menu and can be called directly by users.

2. Agent Skill (`SKILL.md`)

Proactive fork management by Claude:

Claude automatically suggests forking when exploring multiple approaches
Recognizes when conversation branching would be helpful
Manages forks intelligently based on conversation context
Uses the skill instructions to make decisions about when and how to fork

Example: If you say "Let's try both REST and GraphQL approaches," Claude may proactively suggest or use /fork create 2 --target api-design without you explicitly asking for it.

Requirements

Required

Git
Python 3
jq (JSON processor)

Optional

tmux (highly recommended for best experience)

Troubleshooting

See TROUBLESHOOTING.md for common issues and solutions.

Advanced Usage

Nested Forks

You can create forks within fork branches:

# In main conversation
/fork create 2

# Switch to fork-1
/fork switch fork-xxx-1

# Create sub-forks
/fork create 2

# Now you have:
# - fork-xxx-1
#   - fork-yyy-1
#   - fork-yyy-2
# - fork-xxx-2

Programmatic Access

Use the Python state manager directly:

# List all forks
python3 src/state_manager.py list

# Export checkpoint
python3 src/state_manager.py export fork-xxx-1 backup.json

# Import checkpoint
python3 src/state_manager.py import backup.json

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT License - see LICENSE file for details

Support

Issues: https://github.com/mcfearsome/fork-yeah/issues
Discussions: https://github.com/mcfearsome/fork-yeah/discussions
Documentation: https://github.com/mcfearsome/fork-yeah/wiki

Credits

Created by mcfearsome for the Claude Code community.

Happy Forking! 🍴

Installation

Option 1: Use slash command in Claude Code

/install-skill https://github.com/mcfearsome/fork-yeah

Option 2: Clone to skills directory

# Global (all projects)

git clone https://github.com/mcfearsome/fork-yeah ~/.claude/skills/fork-yeah

# Project-specific

git clone https://github.com/mcfearsome/fork-yeah .claude/skills/fork-yeah

Add MCP server to .cursor/mcp.json:

{
  "mcpServers": {
    "skillz": {
      "command": "npx",
      "args": ["-y", "skillz-mcp", "https://github.com/mcfearsome/fork-yeah"]
    }
  }
}

Restart Cursor after adding the configuration.

Option 1: Use Gemini CLI command

gemini extensions install https://github.com/mcfearsome/fork-yeah

Option 2: Clone to extensions directory

git clone https://github.com/mcfearsome/fork-yeah ~/.gemini/extensions/fork-yeah

managing-forks

SKILL.md

Managing Forks - Conversation Branching for Claude Code

When to Use This Skill

Core Commands

Creating Forks

Listing Forks

Viewing Fork Hierarchy

Switching Between Forks

Checking Fork Status

Merging Forks

Deleting Forks

Workflow Examples

Example 1: Exploring Multiple Implementation Approaches

Example 2: Trying Different Design Patterns

Example 3: Nested Forks for Sub-Experiments

Best Practices

Before Creating Forks

During Fork Work

After Fork Work

Technical Details

What Happens When You Create a Fork

Fork Data Structure

Metadata Fields

Error Handling

Common Issues

Recovery

Limitations

Integration with Terminal Multiplexing

tmux Mode (Recommended)

Fallback Modes

Configuration

Tips for Effective Fork Usage

Related Documentation

README

🍴 fork-yeah

Features

Quick Start

Installation

Basic Usage

How It Works

The Fork Workflow

Example Scenario

Commands Reference

/fork create <number> [--target <branch_name>]

/fork list

/fork switch <fork_id>

/fork tree

/fork status

/fork merge <fork_id>

/fork delete <fork_id>

Terminal Modes

tmux Mode (Recommended)

Fallback Modes

Configuration

File Structure

How the Plugin Works

1. Slash Commands (commands/ directory)

2. Agent Skill (SKILL.md)

Requirements

Required

Optional

Troubleshooting

Advanced Usage

Nested Forks

Programmatic Access

Contributing

License

Support

Credits

`/fork create <number> [--target <branch_name>]`

`/fork list`

`/fork switch <fork_id>`

`/fork tree`

`/fork status`

`/fork merge <fork_id>`

`/fork delete <fork_id>`

1. Slash Commands (`commands/` directory)

2. Agent Skill (`SKILL.md`)