Ai Parallel Workflow

Parallel AI Development Workflow

Scaling development by leveraging Git Worktrees, Tmux (Workmux), and multiple isolated AI agents.

🧠 The Concept: Multi-Agent Parallelism

Traditional AI agent workflows suffer from a “single-threaded bottleneck.” If an agent is deep into refactoring a core library in your main repository directory, you cannot simultaneously ask it (or another agent) to quickly fix a CSS bug without risking file conflicts, broken evaluation states, or lost context.

Git Worktrees solve this. A worktree is a linked, physical directory on your filesystem that checks out a different branch of the same repository. By using the Workmux tool (which wraps git worktree and tmux), we can achieve true parallel development.

Yes, you can have multiple AI agents working simultaneously in different worktrees.

  • Agent A can be in .worktrees/refactor-themes running complex Nix evaluations.
  • Agent B can be in .worktrees/fix-hyprland-bug editing Wayland configs.
  • Human can be in the main dev branch reviewing code or doing normal work.

They all share the same local Git database, making branching and merging instantaneous, but their file systems and hey check evaluations are completely isolated.

🚀 Step-by-Step Guide for Parallel Refactoring

Step 1: Create Isolated Workspaces (Via Workmux)

Whenever a new significant task or refactor is planned, do not use the main dev directory. Instead, provision a new worktree.

  1. Open the Workmux Menu: In your terminal, press your Tmux Workmux binding: Prefix + w.
  2. Create the Branch/Worktree: Type a new branch name indicating the task (e.g., refactor/theme-submodules or feature/niri-hooks) and press Enter.
  3. Repeat for Parallel Tasks: You can repeat this process to create multiple worktrees (e.g., .worktrees/refactor-themes, .worktrees/feature-hooks).

Note: You can attach a different AI agent session (like Aider, Claude Code, or Gemini CLI) to each specific .worktrees/<branch-name> directory.

Step 2: The “Surgical” Implementation Phase

Inside each isolated Workmux session, the agent/human performs the modifications.

  • Isolation Guarantee: Breaking the Nix configuration in .worktrees/refactor-themes will not affect the main dev folder or any other worktree.
  • Iterative Commits: Agents should commit their work frequently within their respective worktrees.

Step 3: The Verification Loop (Crucial for Worktrees)

Because changes in a worktree are isolated, you must not run hey sync to test them, as hey sync applies the configuration to the live system. Instead, use the dry-run and evaluation tools inside the specific worktree:

  1. Syntax Check: 
    hey check syntax
  2. Deep Evaluation Check (Catches infinite recursion): 
    hey check eval --host <your-host-name>
  3. Local Dry Build (Safe logic test): 
    nix build .#nixosConfigurations.<your-host-name>.config.system.build.toplevel

Step 4: Merging and Integration

Once an agent finishes a task and the verification loop (hey check eval) passes in their worktree:

  1. Commit the final state in the worktree: 
    git add .
git commit -m "feat: complete subsystem refactor"
  2. Switch back to the main dev session (using Tmux session switcher Prefix + S or Prefix + /).
  3. Merge the worktree’s branch: 
    git merge <branch-name>
  4. Deploy to the Live System: 
    hey sync

Step 5: Clean Up

Once a parallel task is successfully merged into dev and deployed, clean up the workspace to reclaim disk space and keep your Tmux sessions tidy.

  1. Remove the physical worktree directory: 
    git worktree remove .worktrees/<branch-name>
  2. Delete the merged branch: 
    git branch -d <branch-name>

⚠️ Best Practices for Multi-Agent Workflows

  1. Scope Boundaries: Ensure that parallel agents are working on orthogonal parts of the codebase (e.g., one agent on modules/themes/, another on lib/hey/). If they touch the same files, you will have to resolve Git merge conflicts manually in the dev branch.
  2. Always Run Checks: Never merge a worktree branch back to dev unless hey check eval has passed successfully inside that worktree.
  3. Context Awareness: If you start an AI agent inside a worktree, ensure its “working directory” context is set to that specific .worktrees/xyz folder so it doesn’t accidentally read files from the main repo.