Dev Workspace

A unified terminal development environment combining:

• zmux - Zellij-based git worktree manager
• Claude Workflows - AI-powered development commands and agents
• Terminal IDE - Neovim + lazygit + delta for a complete dev setup

Quick Start

# Clone and install
git clone https://github.com/YOU/dev-workspace.git
cd dev-workspace
./install.sh

# Set up a project
./install.sh ~/projects/my-app --init --namespace ABC

# Start working on a Linear ticket
cd ~/projects/my-app
zmux fc 123  # Creates worktree + starts Claude with /full-cycle ABC-123

# Or review PRs in parallel
zmux pr 261 263 265  # Opens 3 tabs, each reviewing a PR

What's Included

dev-workspace/
├── install.sh                  # Installation script
├── bin/
│   └── zmux                    # Git worktree + Zellij manager
├── claude/
│   ├── agents/                 # Subagent definitions
│   │   ├── explorer.md
│   │   ├── planner.md
│   │   ├── implementer.md
│   │   ├── reviewer.md
│   │   ├── documenter.md
│   │   ├── summarizer.md
│   │   └── pr-reviewer.md
│   └── commands/               # Slash commands for Claude Code
│       ├── linear-task.md
│       ├── explore.md
│       ├── plan.md
│       ├── implement.md
│       ├── review.md
│       ├── review-response.md
│       ├── summarize.md
│       ├── document.md
│       ├── commit.md
│       ├── full-cycle.md
│       └── pr-review.md
├── scripts/
│   └── multi-model-review.sh   # Multi-AI PR review orchestrator
├── config/
│   └── nvim/                   # Neovim configuration
│       └── init.lua
└── templates/
    ├── CLAUDE.md.template
    ├── mcp.json.template
    └── zmux.yaml.template

Components

1. zmux - Worktree Manager

zmux replaces tmux-based workmux with Zellij for better mouse support and workflow integration.

| Command | Description | |---------|-------------| | zmux fc <ticket> [...] | Create worktree(s) + start /full-cycle | | zmux pr <pr#> [...] | Create worktree(s) + start /pr-review | | zmux add <branch> | Create worktree and zellij tab | | zmux remove <branch> | Remove worktree and close tab | | zmux merge <branch> | Merge to main and cleanup | | zmux list | Show active worktrees | | zmux goto <branch> | Switch to tab by name | | zmux attach | Attach to zmux session |

Parallel workflows:

# Work on 3 Linear tickets simultaneously
zmux fc 100 101 102

# Review 3 PRs in parallel
zmux pr 261 263 265

# Use Alt+1/2/3 or click tabs to switch

2. Claude Workflows

A complete workflow system with specialized agents:

| Agent | Role | |-------|------| | @explorer | Understand tickets + analyze codebase | | @planner | Create detailed implementation plans | | @implementer | Execute plans with precision | | @reviewer | Thorough code review | | @summarizer | Create summaries and commit messages | | @documenter | Update documentation | | @pr-reviewer | Multi-model PR review synthesis |

Main commands:

/linear-task ABC-123    # Load a Linear ticket
/full-cycle ABC-123     # Complete automated workflow
/pr-review 456          # Multi-model PR review

Workflow stages:

1. Explore → 2. Plan → [CHECKPOINT] → 3. Implement →
4-7. Review Loop → 8. Summarize → [CHECKPOINT] →
9. Document → 10. Commit

3. Terminal IDE

A three-pane development environment:

┌──────────────┬────────────────────────┬─────────────────┐
│ lazygit      │ neovim                 │ claude          │
│              │                        │                 │
│ • File tree  │ • Auto-reload on save  │ • AI assistant  │
│ • Git status │ • Side-by-side diffs   │ • Edits files   │
│ • Stage/diff │ • diffview.nvim        │ • Shows diffs   │
└──────────────┴────────────────────────┴─────────────────┘

Installation

System Requirements

# macOS
brew install neovim lazygit zellij git-delta fzf ripgrep gh

# Ubuntu/Debian
sudo apt install neovim ripgrep fzf
# Install lazygit, zellij, gh, delta from GitHub releases

Install Dev Workspace

# Clone
git clone https://github.com/YOU/dev-workspace.git ~/dev-workspace

# Install (global tools only)
cd ~/dev-workspace
./install.sh

# This will:
# 1. Install zmux to ~/.local/bin/
# 2. Configure git-delta (optional)
# 3. Set up Neovim config (optional)

Project Setup

New Project

./install.sh ~/projects/my-app --init --namespace ABC

This creates:

• .zmux.yaml - Worktree and pane configuration
• .claude/ - Commands and agents
• CLAUDE.md - Project-specific AI instructions (customize this!)
• .mcp.json - MCP server configuration
• scripts/ - Workflow scripts

Existing Project

# Update workflow files (preserves your custom agents/commands)
./install.sh ~/projects/my-app

# Use --symlink for auto-updates from source
./install.sh ~/projects/my-app --symlink

# Use --force to overwrite existing files
./install.sh ~/projects/my-app --force

Install Options

| Option | Description | |--------|-------------| | --dry-run | Show what would be done without doing it | | --symlink | Symlink files for auto-updates from source | | --init | Create CLAUDE.md and .mcp.json (new projects) | | --namespace <n> | Linear namespace (required with --init) | | --force | Overwrite existing files |

Configuration

.zmux.yaml

# Where to create worktrees
worktree_dir: "../{{REPO_NAME}}__worktrees"

# Linear integration (use 'zmux fc 123' instead of 'zmux fc ABC-123')
linear_prefix: ABC

# Panes for each worktree tab
panes:
  - name: claude
    command: claude
    focus: true
  - name: shell
    command: ""

# File handling
files:
  symlink:
    - node_modules
    - .pnpm-store
  copy:
    - .env.local

CLAUDE.md

The CLAUDE.md file gives Claude context about your project:

# Project Name

## Overview
Brief description of the project.

## Tech Stack
- Language/framework
- Database
- Key dependencies

## Development Commands
- `pnpm dev` - Start dev server
- `pnpm test` - Run tests

## Code Conventions
- Style guide rules
- Architecture patterns

Workflows in Detail

Linear Ticket Workflow (/full-cycle)

zmux fc 123
  │
  ├─→ Creates worktree: abc-123
  ├─→ Opens Zellij tab with Claude + shell panes
  └─→ Claude runs /full-cycle ABC-123
        │
        ├─ 1. Load ticket from Linear API
        ├─ 2. @explorer analyzes codebase
        ├─ 3. @planner creates implementation plan
        │      └─ [CHECKPOINT: User approves plan]
        ├─ 4. @implementer executes plan
        ├─ 5. @reviewer performs code review
        ├─ 6-7. Review loop (max 3 iterations)
        ├─ 8. @summarizer presents changes
        │      └─ [CHECKPOINT: User approves]
        ├─ 9. @documenter updates docs
        └─ 10. Commit with generated message

PR Review Workflow (/pr-review)

zmux pr 456
  │
  ├─→ Creates worktree: pr-456
  ├─→ Opens Zellij tab
  └─→ Claude runs /pr-review 456
        │
        ├─ 1. Fetch PR from GitHub (diff, comments)
        ├─ 2. Run multi-model-review.sh
        │      ├─ Claude analysis
        │      ├─ Gemini analysis
        │      └─ OpenAI analysis
        ├─ 3. @pr-reviewer synthesizes feedback
        └─ 4. Output actionable gh CLI commands

Tips & Tricks

Quick Navigation

# Inside Zellij
Alt+1/2/3       # Switch tabs
Ctrl+p n        # New pane
Ctrl+p x        # Close pane
Ctrl+o w        # Session picker

# Inside Neovim
<leader>ff      # Find files
<leader>fg      # Live grep
<leader>gd      # Git diff view

Parallel PR Reviews

# Start reviewing multiple PRs
zmux pr 261 263 265

# Each tab has Claude pre-loaded with /pr-review
# Switch between them with Alt+1/2/3

Copy from Terminal

Zellij supports native mouse selection:

• Select text with mouse → auto-copies
• Right-click to paste
• No special copy mode needed!

Troubleshooting

"Command not found: zmux"

# Add to PATH
export PATH="$HOME/.local/bin:$PATH"

# Or re-run install
~/dev-workspace/install.sh

Zellij session won't start

# Check for existing sessions
zellij list-sessions

# Kill stuck sessions
zellij kill-session zmux

Claude commands not showing

# Verify .claude directory exists
ls -la .claude/commands/

# Re-install to project
~/dev-workspace/install.sh /path/to/project --force

License

MIT