Merge

What Is Merge?

The "Merge" skill for Claude Code, available via /hub:merge, is a specialized utility designed to streamline the workflow when integrating contributions from multiple agents. In collaborative development environments—especially those powered by agent-based or human-in-the-loop code generation—sessions often yield multiple candidate solutions. The Merge skill automates the process of merging the branch from the winning agent into your base branch, archives the contributions from non-winning agents via Git tags, and cleans up the workspace by removing redundant branches and worktrees. This operation ensures your main codebase remains clean, reproducible, and auditable.

Why Use Merge?

In agent-driven or competitive coding workflows, multiple agents may propose solutions to a given task. Evaluations identify the most suitable or highest-performing candidate, but integrating this solution while preserving the work and context of other agents can be tedious and error-prone if done manually. The Merge skill addresses this challenge by:

• Automating the winning branch merge, reducing human error.
• Archiving losing branches with tags for future reference, maintaining a full audit trail.
• Cleaning up worktrees to reduce repository clutter and improve performance.
• Generating a standardized merge summary for traceability.

By incorporating Merge into your workflow, you can focus on evaluating agent outputs and making decisions, rather than dealing with low-level repository management.

How to Get Started

To use the Merge skill, ensure you have the skill installed from the GitHub source and that your repository is configured for agenthub workflows. The command-line interface provides flexible invocation patterns:

## Merge the winner from the latest evaluation session
/hub:merge

## Merge the winner from a specific session
/hub:merge 20260317-143022

## Merge a specific agent as the winner for a session
/hub:merge 20260317-143022 --agent agent-2

After running the command, the Merge skill will:

1. Identify the winner (either specified via --agent or inferred from the latest evaluation results).
2. Merge the winning agent’s branch into your base branch, typically main or master.
3. Archive the branches of all non-winning agents using Git tags.
4. Delete the non-winning branches and clean up any associated worktrees.
5. Create a merge summary in your .agenthub/board/results/merge-summary.md file for documentation and traceability.

Key Features

• Automatic Winner Selection: By default, Merge picks the top-ranked agent from the latest /hub:eval, but you can override this to select any agent.
• Clean Git Integration: The tool uses standard Git operations to merge, tag, and delete branches, ensuring compatibility and reliability.
• Archival via Tags: Rather than deleting non-winning agent branches outright, Merge tags their final commit, making it easy to revisit or audit their contributions later.
• Worktree Cleanup: Temporary working directories (worktrees) created for agent branches are removed to keep your repository lean.
• Standardized Summaries: After a successful merge, a Markdown summary is created, capturing task details, winner information, and session metadata.

Practical Example

Suppose you have a session with three agents: agent-1, agent-2, and agent-3. After evaluation, agent-2 is determined to be the winner. To merge the result, you would run:

/hub:merge 20260317-143022 --agent agent-2

Behind the scenes, Merge will execute:

git checkout main
git merge --no-ff hub/20260317-143022/agent-2/attempt-1 \
  -m "hub: merge agent-2 from session 20260317-143022

Task: <task description>
Winner: agent-2
Session: 20260317-143022"

For each losing agent, it will archive:

## For agent-1 (loser)
git tag hub/archive/20260317-143022/agent-1 hub/20260317-143022/agent-1/attempt-1
git branch -D hub/20260317-143022/agent-1/attempt-1

## For agent-3 (loser)
git tag hub/archive/20260317-143022/agent-3 hub/20260317-143022/agent-3/attempt-1
git branch -D hub/20260317-143022/agent-3/attempt-1

Worktrees are cleaned up using:

python skills/merge/scripts/session_manager.py --cleanup 20260317-143022

Finally, a summary is written to .agenthub/board/results/merge-summary.md.

Best Practices

• Review Before Merge: Always verify the winning branch before merging, whether selected automatically or manually. Use code review tools or manual inspection as appropriate.
• Keep Session IDs Consistent: Use consistent and descriptive session identifiers to make tracking and auditing easier.
• Automate in CI/CD: Consider integrating Merge into your continuous integration pipeline to automate merges after successful evaluations.
• Monitor Archive Tags: Regularly audit your Git tags to ensure that the archive does not become unwieldy. Old, unnecessary tags can be pruned if space or clarity becomes an issue.
• Document Merge Summaries: Treat the generated Markdown summaries as part of your project history. They provide valuable context for future contributors or audits.

Important Notes

• Irreversible Deletion: While losing branches are archived via tags, the branches themselves are deleted. Ensure your repository’s tag retention policy aligns with your compliance and recovery needs.
• Merge Conflicts: In rare cases, merging the winning branch may result in conflicts. Resolve these conflicts manually before proceeding.
• Skill Path Dependencies: The cleanup script relies on the skill path structure. If you move or rename the skill directory, update your scripts accordingly.
• Repository State: Always ensure your repository is in a clean state before running /hub:merge to prevent accidental data loss or inconsistent merges.
• Agenthub Integration: The Merge skill is designed for agenthub workflows and may require adaptation for standalone or non-agent-based repositories.

By following these guidelines and integrating the Merge skill into your development process, you can ensure a robust, auditable, and scalable workflow for agent-driven codebases.