Technical Briefing: parallel-code

The Problem

AI coding agents operate best with isolated environments, but teams currently face a choice between managing git worktrees and branches manually across terminal windows, or being locked into a single IDE extension. This fragmentation means agents either step on each other's changes or require context-switching that breaks workflow momentum. There is no single interface that gives each agent its own git branch and worktree automatically.

What This Does

parallel-code is a desktop application (Electron + SolidJS + TypeScript) that automates git worktree isolation for AI coding agents. The codebase contains 254 files across src/ (161 files) and electron/ (32 files), with TypeScript dominating at 117 files and TSX at 66. Entry points include src/App.tsx, src/index.tsx, and electron/main.ts. The app integrates with Claude Code, Codex CLI, and Gemini CLI through an IPC layer in electron/ipc/, allowing agents to be spawned in isolated worktrees with symlinked node_modules. When a task is created, the system creates a git branch, sets up a worktree, symlinks git-ignored directories, and spawns the agent — all from one interface. Merge back to main happens from the sidebar.

How It Is Wired

Execution starts at src/App.tsx entry points: handleDrop (line 161), handlePaste (line 373), and handleDragEnter (line 139) feed into createSignal (called from 46 places per the internal call graph). State flows through src/store/store which has 35 importers and 16 dependencies with 0.31 instability — the hub module where 48 others depend. The store dispatches via createSignal from src/lib/fontScale.ts (19 callers). IPC communication runs through electron/ipc/channels.ts (42 importers, 0 dependencies, zero instability) and src/lib/ipc.ts (23 importers).

Six modules participate in circular imports: src/store/focus.ts, src/store/tasks.ts, and src/store/projects.ts. Nineteen repeated 6-line code blocks appear across 59 files, notably in electron/ipc/agents.ts, src/ipc/types.ts, and electron/ipc/ask-code-minimax.ts. The deepest nesting (6 levels) occurs in src/components/ChangedFilesList.tsx, src/components/HelpDialog.tsx, and src/components/TaskStepsSection.tsx. Three outbound network calls happen through electron/ipc/ask-code-minimax.ts (minimax API key configuration), and one cryptographic operation exists in the codebase.

How To Use It

Setup: Clone with git clone https://github.com/moses-y/parallel-code. Install dependencies via npm install (package.json present). The Dockerfile in docker/ builds the container image.

Configuration: No environment variables are required for basic operation. Minimax API key can be set in Settings if using the Minimax model; otherwise Claude Code is the default. The app runs on macOS and Linux.

Running it: Launch via npm start from the root, or build with npm run build. The Electron main process starts at electron/main.ts. The Tailscale QR code feature enables phone monitoring over Wi-Fi.

Real-World Use

A team of five developers wants to run Claude Code, Codex, and Gemini simultaneously on five different features. Without parallel-code, they'd each manage separate terminal windows, manually create worktrees, and risk branch conflicts. With parallel-code, one developer creates five tasks through the GUI. Each agent spawns in its own git worktree with isolated dependencies. The interface shows real-time status across all five agents. When work is complete, the developer merges each branch back to main from the sidebar — all change history is reviewable through normal git tooling. The phone QR code lets a manager monitor progress from a mobile device without interrupting the agents.

Code Health & Issues

The static analysis (186 of 186 code files examined) identifies 11 findings across the SDLC:

  • HIGH — Pin third-party GitHub Actions to commit SHA in .github/workflows; softprops/action-gh-release@v2 is a mutable tag risk for secrets.
  • HIGH — CI does not invoke the test suite; 26 test files exist but no test command appears in any workflow.
  • MEDIUM — GITHUB_TOKEN permissions not declared in .github/workflows/ci.yml; inherits repository defaults giving broad access.
  • MEDIUM — Dependabot or Renovate not configured; no update bot present despite package-lock.json.
  • MEDIUM — Docker base image ubuntu:22.04 not pinned by digest; mutable tag means varying CVE sets between builds.
  • MEDIUM — No dependency vulnerability scan in CI pipeline.
  • MEDIUM — Large binaries demo.mov (20.3MB), demo.gif (8.3MB), longer-video.gif (6.0MB) committed to repository; every clone pays for data not diffed.
  • MEDIUM — 12 generated build files committed to build/, creating stale bundle/review mismatch.
  • MEDIUM — checkout retains persist-credentials: true by default; token stays in .git/config for all later steps.
  • MEDIUM — Dockerfile has no USER directive; process runs as root against all mounted volumes.
  • Low — One additional finding at lower severity.

The Bottom Line

The codebase is well-structured with clear IPC separation between src/ and electron/, and the core problem — automating git worktree isolation for parallel AI agents — is executed competently. However, the circular import cycle in the store modules, the oversized IPC files (electron/ipc/git.ts at 1313 lines), and the 190 duplicated code blocks across 59 files represent tangible technical debt that will slow feature work. The CI hygiene issues (missing test invocation, unpinned Actions, unpinning Docker base) are fixable with modest effort. Teams that need genuine parallel AI agent workflows with reviewable git history will find this functional today, but should plan to address the stability and security findings before production deployment.