Fixing 6 GitHub Issues in Parallel with Claude Code: Worktrees and Agents

Introduction

We develop a web-based viewer for historical sources structured in TEI/XML, built with Nuxt 2 + Vue 2 + Vuetify. This article describes how we used Claude Code’s worktree and agent features to address 6 GitHub Issues in parallel.

Issues Addressed

Approach: Worktrees × Parallel Agents

Claude Code can run multiple agents in parallel, each in an isolated git worktree. We grouped the issues into 4 categories and launched 4 agents simultaneously.

Agent 1: fix/nested-tags     → Group A (3 issues, same root cause)
Agent 2: fix/legend-indent   → Group B
Agent 3: fix/analytics-links → Group C
Agent 4: fix/keyword-search  → Group D

Each agent works in its own worktree, so there is no interference between parallel tasks.

Fix Details

Group D: Search Plugin Crash

Root cause: A configuration value loaded from an environment variable was undefined, causing a TypeError crash during search execution.

Fix: A single-line null guard resolved the issue. The agent accurately identified the root cause.

Group A: Nested Element Display Bugs

These three issues appeared to be separate problems but shared a common root cause.

Root cause: The TEI XML preprocessing script did not correctly handle nested elements. Specifically, when converting text ranges marked by anchor pairs into structured elements, inner (nested) elements were filtered out, causing text and clickable annotations to be lost.

Fix: Three changes were made to the preprocessing script:

1. Process inner elements first: Sort by range size (ascending) to process innermost elements before outer ones
2. Fix mixed content assembly bug: Use BeautifulSoup’s NavigableString to prevent data loss when tags and strings are mixed
3. Update nesting depth attributes: After conversion, count ancestor elements and set attribute values accordingly (needed for color-coded display in the viewer)

The agent’s initial fix modified the viewer component (Vue.js), but the real solution was in the data conversion pipeline (Python script). After verifying the agent’s output, we manually traced back to the root cause.

Group B: Legend Page Indentation

Root cause: Two problems were compounded:

1. The Vue.js component converted style attributes via DOM manipulation, but changes were not preserved through outerHTML → JSON conversion
2. The latest TEI source repository had changed CSS property names, so the fix worked locally (with older data) but failed in the CI environment

Fix: Changed to resolve styles after JSON conversion, and added support for both old and new CSS property names.

This issue took the longest to diagnose due to the data discrepancy between local and CI environments.

Group C: Analytics Page Link Breakage

Root cause: The linked page files did not exist.

Fix: The agent created two new pages. However, i18n support (translation key registration) and layout consistency with other pages were insufficient, requiring manual follow-up fixes.

Established Workflow

Through this process, we established the following workflow:

1. Create branch: Cut a fix/issue-description branch from dev
2. Update data source: git pull the external data repository to latest
3. Local verification: Checkout branch → npm run dev → verify in browser
4. Merge & push to dev: Merge to dev and push (CI auto-deploys)
5. Verify on staging: Check the deployed environment
6. Request review on issue: Add assignees and comment with verification steps
7. Close: Close only after third-party confirmation

Progress Management with GitHub Projects

We introduced GitHub Projects V2 with 4 statuses: Todo → In Progress → Review Pending → Done to track issue phases.

Lessons Learned

1. Watch for Data Differences Between Local and CI

The external data repository was newer in CI than the local copy, causing a fix that worked locally to fail in the deployed environment. We added pulling the latest data source before starting work to our workflow.

2. Close Issues Only After Third-Party Review

Initially, agents automatically closed issues upon completing fixes. However, issues should only be closed after a third party has verified the fix. This is a basic quality control practice, but it is easily overlooked when delegating to AI tools.

3. Parallel Work with Worktrees Is Effective

Four agents working simultaneously in independent worktrees allowed efficient parallel development without interference. However, agent output is not always perfect, so manual review and additional fixes are sometimes necessary.

4. Identifying the Root Cause Matters

The three issues in Group A appeared to be separate problems but all stemmed from the same location in the data conversion pipeline. The agent proposed a viewer-side fix, but the essential solution was fixing the data conversion. It is important not to blindly accept AI suggestions and to trace back to the root cause.

5. Verify CI Behavior

Confirming that deployments succeed is also important. In this case, a CI job had been cancelled, meaning a fix was not actually deployed despite being pushed.

Conclusion

By leveraging Claude Code’s worktree and agent features, we efficiently addressed 6 issues in parallel. At the same time, the process revealed that human verification remains essential — validating agent output, ensuring data consistency between local and CI environments, and establishing proper third-party review processes.

Note that the approach described in this article reflects the state of tools as of March 2026. Claude Code is rapidly evolving with new features such as co-works, and the way we handle parallel work and reviews is changing accordingly. Workflows themselves need to be continuously revisited as the tools improve.