Technical Briefing: dmux

The Problem

Teams using AI coding agents face conflicts when multiple agents operate on the same codebase. Branch divergence, merge collisions, and state contamination waste time and introduce errors. dmux addresses this by assigning each agent an isolated git worktree and tmux pane, ensuring complete separation of concurrent development efforts.

What This Does

dmux is a terminal-based tool that creates tmux panes, each with its own git worktree and branch. When a user starts a new pane (n key), dmux scaffolds an isolated working copy, launches supported agent CLIs (Claude Code, Codex, Cline, Gemini, etc.), and manages branch/commit naming automatically. Completion triggers a merge workflow (m key) that auto-commits, merges, and cleans up. The codebase comprises five self-contained projects: src (238 files, 235 code files), __tests__ (107 files), scripts (7 files), coverage (188 files), and frontend (15 files). Execution begins at init in src/index.ts:175, which reaches 150 functions and is itself called from one place. Key entry points also include start in src/services/ConfigWatcher.ts:40 (reaches 34 functions, called by nothing else in the repo) and main in src/components/popups/agentChoicePopup.tsx:244 (reaches 92 functions, called from one place). The traced paths show execution reaches the filesystem via ensureDmuxDirectory [fs.mkdir], ensureHelperRunning [fs.mkdir], and atomicWriteFile [crypto via randomBytes(8).toString, filesystem via fsPromises.unlink]. The most connected module is src/types (94 importers, 4 imports, instability 0.04, in a cycle with src/utils/agentLaunch and src/services/TmuxService), serving as a hub with blast-radius risk: 94 modules depend on it, and changes ripple widely.

How It Is Wired

Control flows through a resolved call graph of 2695 edges between internal functions. getInstance is called from 143 places, the most distinct call site, followed by executeWithRetry (36), getSettings (32), and getPaneDisplayName (32). The import graph contains 15 modules in circular dependencies, primarily in src/types.ts, src/utils/agentLaunch.ts, and src/services/TmuxService.ts — these cycles increase cognitive load for modifications. Oversized files compound this: src/utils/agentLaunch.ts (708 lines), src/services/TmuxService.ts, and src/utils/settingsManager.ts each exceed 700 lines, hard to hold in one head and wide ripple effects. Duplicated code appears in 370 repeated 6-line blocks across 106 files, notably in .codex/hooks/dmux-stop-hook.cjs, src/utils/codexHooks.ts, and src/utils/claudeHooks.ts. Entry point init routes through src/services/LogService.ts (27 functions, 46 callers), src/services/TmuxService.ts (78 functions, 29 callers, calls into 4), and src/utils/agentLaunch.ts (29 functions, 14 callers, calls into 6). Effects outside the process include filesystem writes (via atomicWriteFile, atomicWriteJson) and external command execution (via runCommand in merge workflows). No paths to network or database were mapped; only filesystem and command-line effects are resolved.

How To Use It

Setup:

npm install -g dmux
# or with pnpm (configured package manager)
pnpm install -g dmux

Configuration: No configuration file is required for basic use. Environment variables for agent CLIs (Anthropic API key for Claude Code, OpenAI key for Codex, etc.) are set per-agent in the user's environment. The repo contains docs/package.json and frontend/package.json for the documentation and web frontend subprojects, but these are not needed for the core tool.

Running it:

cd /path/to/your/project
dmux

Press n to create a new pane, type a prompt, select one or more agents (or none for a plain terminal), and dmux handles worktree/branch setup and agent launch. Branch overrides are available via the pane menu. Requirements: tmux 3.0+, Node.js 18+, Git 2.20+, at least one supported agent CLI.

Real-World Use

A development team splits a feature into three parallel tasks: UI redesign, backend API, and database migration. Each agent works in a dedicated dmux pane with isolated worktrees. The UI agent lands in a feature/ui-refactor branch, the backend agent in feature/api-endpoint, and the migration agent in feature/db-schema. When each task is complete, the operator opens the pane menu (m), selects Merge, and dmux auto-commits changes, merges into main, and cleans the worktree. No branch conflicts occur because each pane's worktree was created from a distinct branch at inception. The global pane visibility (H hides all others, h hides/shows selected) lets the team focus on one task at a time while preserving all in-flight work.

Code Health & Issues

Findings from static analysis of 376 code files:

  • HIGH/soundness — Import cycle member (15 files): src/types.ts, src/utils/agentLaunch.ts, src/services/TmuxService.ts. Participates in circular import dependency. Fix: extract shared types, invert a dependency, or defer an import.
  • HIGH/clarity — Hub module (17 files): src/types.ts, src/services/LogService.ts, src/utils/agentLaunch.ts. 94 modules depend on src/types; churn here has high-blast-radius. Fix: keep it stable and small; move volatile logic out.
  • HIGH/cognitive_load — Oversized file (9 files): src/utils/agentLaunch.ts (708 lines), src/services/TmuxService.ts, src/utils/settingsManager.ts. Fix: split into cohesive units by responsibility.
  • MEDIUM/cognitive_load — High branching density (14 files): src/utils/layoutManager.ts, src/utils/git.ts, src/utils/tmux.ts (111 branch points over 333 lines). Fix: decompose decision-heavy logic; consider table/strategy dispatch.
  • MEDIUM/cognitive_load — Deep nesting (4 files): src/components/inputs/CleanTextInput.tsx, src/FileBrowserApp.tsx, src/components/popups/newPanePopup.tsx (max indentation depth 7). Fix: flatten with early returns/guard clauses; extract inner blocks.
  • HIGH/clarity — Duplicated code blocks (370 repeated 6-line blocks across 106 files): .codex/hooks/dmux-stop-hook.cjs, src/utils/codexHooks.ts, src/utils/claudeHooks.ts, src/utils/grokHooks.ts. Fix: extract shared helpers; DRY the repeated logic.

Code health audit (8 findings, 0 critical):

  • HIGH — Pin third-party GitHub Actions to commit SHA. Evidence: pnpm/action-setup@v4 in .github/workflows. A tag can move, so the action running with your token and secrets is whatever its owner last pushed. Fix: replace @vN with 40-character commit SHA; let Dependabot bump SHAs.
  • HIGH — Make CI invoke the test suite it has. Evidence: 115 test files, no test command in any workflow. Fix: add a test step to the existing workflow.
  • MEDIUM — Enable Dependabot or Renovate. Evidence: 3 manifest(s), no update bot configured. Fix: commit .github/dependabot.yml covering repo ecosystems plus github-actions.
  • MEDIUM — Gate pull requests on dependency vulnerability scan. Evidence: no dependency scan in CI. Fix: add dependency-review-action on pull_request, or osv-scanner on push and schedule.
  • MEDIUM — Move large binaries to Git LFS or out of the repo. Evidence: docs/public/dmux.mp4 (13.6MB), dmux.gif (8.9MB). Fix: track with LFS or move to object storage with setup step.
  • MEDIUM — Set persist-credentials: false on checkout. Evidence: checkout keeps the token, then dependencies are installed in .github/workflows/publish.yml. Fix: add with: persist-credentials: false and pass explicit token only to the push step.
  • LOW — Set timeout-minutes on workflow jobs. Evidence: 1 workflow declares no job timeout in .github/workflows/publish.yml. Fix: add realistic timeout-minutes to each job.
  • LOW — Add convention files the project lacks. Evidence: missing .editorconfig, .gitattributes, formatter config. Fix: add .editorconfig, .gitattributes with text=auto eol=lf, and formatter config.

The Bottom Line

dmux solves a genuine pain point for teams running multiple AI coding agents by enforcing git worktree isolation at the tmux pane level. The codebase is functional and well-structured for its scope, with a clear entry point and resolvable call graph. However, the circular import cycle involving src/types, src/utils/agentLaunch, and src/services/TmuxService creates a high-blast-radius hub that increases modification risk; the 708-line src/utils/agentLaunch.ts and duplicated hook logic are the largest maintainability concerns. The CI hygiene issues (unpinned Actions, missing test invocation, no dependency scanning) are straightforward to remediate. Teams that need parallel, isolated agent workflows will find dmux immediately useful; teams prioritizing a single, unified development experience may not need the worktree overhead.