Agentic Workflow

An opinionated workflow for parallel AI-assisted feature development using cmux, git worktrees, Claude Code and LazyVim. This repo contains a couple of shell scripts for the workflow.

midnight.demo.mov

Motivation

This repo helps me isolate concurrent agent workspaces in cmux. The scripts in this repo create a clean workflow where git worktrees are helpful:

• Running new-feature spawns a new cmux workspace in a dedicated git worktree
• Each workspace launches dedicated processes in their own cmux workspace tab: Claude code, nvim, an action menu. I'd suggest you to tinker with this aspect of the script so that each invocation of new-feature opens up a workspace that is suitable for your working style.

Alternative Software

• Herdr
  • This HN post enumerates extra options even more
• Superset
• Emdash

Dependencies

• cmux — terminal with workspace/tab management CLI
• Claude Code — claude CLI available in PATH
• Neovim — nvim CLI available in PATH. I recommend LazyVim.
• gum — renders the session controls TUI (menus, confirmations). Install with brew install gum.
• git 2.5+

Installation

Clone or copy the scripts into a directory on your $PATH:

git clone https://github.com/appendjeff/agentic-workflow.git ~/agent-bin

Add ~/agent-bin to your PATH if needed (e.g. in ~/.zshrc):

export PATH="$HOME/agent-bin:$PATH"

Commands

new-feature

Run from anywhere inside a git repository. Creates a new isolated workspace for a feature.

$ new-feature
Feature name: user auth redesign

What it does:

1. Prompts for a feature name (e.g. "user auth redesign")
2. Slugifies it into a branch name: feature/user-auth-redesign
3. Ensures .worktrees/ is in .gitignore (adds it if missing)
4. Fetches origin and creates a worktree branching from origin/main
5. Opens a new named cmux workspace pointed at the worktree
6. Starts claude in the left pane
7. Opens LazyVim (in file picker mode) in a right split pane for browsing/reviewing files
8. Opens a terminal in a bottom split under Claude (~20% height)
9. Refocuses the Claude pane

Result: A new cmux tab named "user auth redesign" with Claude on the top-left, a terminal on the bottom-left (~20%), and nvim on the right — all scoped to .worktrees/user-auth-redesign/ on branch feature/user-auth-redesign.

---

done-feature

Run from inside a feature worktree when the work is complete (merged or abandoned).

$ done-feature
Cleaning up:
  Branch:    feature/user-auth-redesign
  Worktree:  /path/to/repo/.worktrees/user-auth-redesign
  Workspace: 5B485556-0051-4F7C-826D-189F4E61F199

What it does:

1. Guards against running from outside a .worktrees/ directory
2. Navigates to the main repo root
3. Removes the worktree directory
4. Deletes the local branch (-d; prompts before force-deleting if unmerged)
5. Closes the cmux workspace (last, since this kills the shell)

Typical workflow

# Start a new feature from any directory inside your repo
$ new-feature
Feature name: redesign search

# ... Claude works in the isolated worktree ...
# ... you review, merge the PR ...
# when the agent fails, you can use the text editor to fix it or open one of the items from the action menu to improve things

# Clean up from inside the worktree tab
$ done-feature