Skip to content

evanlindsey/zelli-dev

BranchesTags

Repository files navigation

zelli-dev

A modular, additive development environment for terminal-based coding with Claude Code. Optimized for AI-assisted development. Ships with certified vibez.

zelli-dev layout screenshot

What This Gives You

  • Helix - Modern modal text editor (Rust-based, zero config needed)
  • Zellij - Terminal multiplexer with built-in layouts and session management
  • lazygit - Terminal UI for git operations
  • fd - Fast file finder (Helix file picker)
  • ripgrep - Fast content search (Helix global search)
  • bat - Syntax-highlighted file viewer (theme cache for delta)
  • git-delta - Syntax-highlighted git diffs
  • Claude-first layout - 2-column workspace with floating editor, optimized for AI-assisted development
  • Coordinated themes - Matching color palettes across all tools (Catppuccin, Tokyo Night, Rose Pine, Nord, Gruvbox, Dracula)

Layout

┌───────────────────────┬────────────────┐
│                       │                │
│       lazygit         │                │
│        (75%)          │                │
│                       │  Claude Code   │
├───────────────────────┤     (35%)      │
│                       │                │
│      terminal         │                │
│        (25%)          │                │
│                       │                │
└───────────────────────┴────────────────┘
           65%                 35%

         ┌─── Alt+e ───────────────────┐
         │                             │
         │     Helix Editor (floating) │
         │        90% overlay          │
         │                             │
         │   :q to dismiss             │
         └─────────────────────────────┘

Pane purposes:

  • Left top: lazygit for reviewing and staging Claude's changes
  • Left bottom: Terminal for dev servers, tests, build commands
  • Right: Claude Code — where the development happens
  • Floating: Helix editor — summon with Alt+e, dismiss with :q

Themes

Coordinated themes across Helix, bat, delta, and Zellij. Switch all tools at once with zdev theme.

Theme Helix bat/delta Zellij
Catppuccin Mocha (default) catppuccin_mocha Catppuccin Mocha catppuccin-macchiato
Tokyo Night tokyonight_storm tokyonight_storm tokyo-night-storm
Rosé Pine rose_pine rose-pine rose-pine
Nord nord Nord nord
Gruvbox gruvbox gruvbox-dark gruvbox-dark
Dracula dracula Dracula dracula

Note: Zellij uses catppuccin-macchiato (closest to Mocha). Tokyo Night and Rose Pine require .tmTheme downloads for bat/delta — zdev theme handles this automatically.

Manual theme configuration (without zdev)

Helix — ~/.config/helix/config.toml: theme = "catppuccin_mocha"

bat — ~/.config/bat/config: --theme="Catppuccin Mocha"

git-delta — git config --global delta.syntax-theme "Catppuccin Mocha"

Zellij — ~/.config/zellij/config.kdl: theme "catppuccin-macchiato" (must be in config.kdl, not layout files)

Theme docs: Helix | Zellij | bat --list-themes | delta --list-syntax-themes

Platform & Terminal Support

Built for macOS. Tested with iTerm2, Ghostty, Kitty, and VSCode. The installer provides automated theme and configuration setup for these four terminals.

Other terminals with true color and a Nerd Font should work, but are not officially supported. Terminal.app is detected but lacks true color — the installer will suggest alternatives.

Prerequisites

  • Homebrew — used to install all tools (works on macOS and Linux)
  • Claude Code — the layout launches claude in its own pane

Everything else (Zellij, Helix, lazygit, etc.) is installed automatically via Homebrew.

Installation

Quick Install

git clone https://github.com/evanlindsey/zelli-dev.git
cd zelli-dev && ./install.sh

The repo can be safely deleted after installation — everything is copied locally.

The installer will:

  1. ✓ Install missing tools (zellij, helix, lazygit, etc.)
  2. ✓ Copy the Claude-first layout
  3. ✓ Optionally install coordinated Catppuccin theme across all tools
  4. ✓ Optionally configure your terminal emulator's color scheme to match
  5. ✓ Install the zdev CLI for managing your environment

Safe and additive — prompts before overwriting any existing config files. Unlike traditional dotfiles repos that symlink entire config directories, this repo only adds specific files. Your existing configs stay untouched.

What the installer modifies

The installer only writes to these locations:

What Where Protection
Zellij layout ~/.config/zellij/layouts/claude-dev.kdl Prompts if exists
Cheat sheet ~/.config/zellij/CHEATSHEET.md Always updated (our file)
Git delta config ~/.gitconfig (delta/pager sections) Only sets values not already configured
lazygit config ~/.config/lazygit/config.yml Prompts if exists, creates backup
Helix config ~/.config/helix/config.toml Only if you choose themes; prompts + backup
bat config ~/.config/bat/config Only if you choose themes; prompts + backup
Zellij config ~/.config/zellij/config.kdl Only if you choose themes; appends or copies
zdev CLI ~/.local/bin/zdev Copied (standalone)
zdev scripts ~/.config/zdev/scripts/ Supporting scripts for zdev config
PATH entry ~/.zshrc or ~/.bashrc Only if ~/.local/bin not in PATH; prompts
Shell rc ~/.zshrc or ~/.bashrc COLORTERM export; only if not set; prompts

Use --minimal to skip theme and terminal emulator configuration. Use --defaults (or --yes) for non-interactive installation (installs themes, skips terminal emulator setup).

The installer does not touch your existing Helix, Zellij, or bat configs unless you explicitly choose theme installation and confirm the overwrite prompt.

Manual Installation

If you prefer manual installation (from a cloned repo):

# Install tools
brew install zellij helix lazygit fd bat git-delta ripgrep

# Copy layout
mkdir -p ~/.config/zellij/layouts
cp zellij/layouts/claude-dev.kdl ~/.config/zellij/layouts/

# Copy cheat sheet
cp zellij/CHEATSHEET.md ~/.config/zellij/

# Configure git delta
./git/delta-config.sh

# Install zdev CLI
mkdir -p ~/.local/bin ~/.config/zdev/scripts
cp bin/zdev ~/.local/bin/zdev && chmod +x ~/.local/bin/zdev
cp terminal/setup-terminal-theme.sh git/delta-themes-config.sh ~/.config/zdev/scripts/
cp zellij/layouts/claude-dev.kdl ~/.config/zdev/scripts/
chmod +x ~/.config/zdev/scripts/*.sh

# Ensure ~/.local/bin is in your PATH
# Add to ~/.zshrc or ~/.bashrc if needed:
#   export PATH="$HOME/.local/bin:$PATH"

Usage

Launch Your Dev Environment

cd /path/to/your/project
zdev                              # Launch dev environment
zdev --session my-feature         # Launch with named session

zdev CLI

After installation, zdev is a full CLI for managing your environment:

zdev                    # Launch Zellij with claude-dev layout
zdev status             # Show installed tools and current config
zdev theme              # Interactive theme picker
zdev theme tokyo-night  # Switch all tools to Tokyo Night
zdev edit helix         # Open Helix config in $EDITOR
zdev edit zellij        # Open Zellij config
zdev edit layout        # Edit the layout file
zdev config             # Interactive menu to re-run any setup step
zdev uninstall          # Remove everything cleanly
zdev help               # Show all commands

Available themes: catppuccin-mocha, tokyo-night, rose-pine, nord, gruvbox, dracula

Edit targets: helix, bat, zellij, layout, lazygit, delta

Named Sessions

zdev --session my-feature         # Start named session

# Later, reattach
zellij attach my-feature

# List all sessions
zellij list-sessions

Detach (Keep Running)

Press Ctrl+g then d

Your session keeps running in the background. Everything stays alive:

  • Helix with open files
  • lazygit state
  • Running dev servers
  • Test processes

Reattach anytime with zellij attach

Quit (Close Everything)

Press Ctrl+g then q

Quick Reference

Zellij (Ctrl+g = leader)

Alt+e       Toggle floating editor
Ctrl+g p    Switch to next pane
Ctrl+g n    New pane
Ctrl+g x    Close current pane
Ctrl+g d    Detach session (keeps running!)
Ctrl+g q    Quit zellij
Ctrl+g r    Resize mode (then arrows/hjkl)
Ctrl+g ?    Help

Floating Editor

Alt+e       Toggle Helix overlay
:q          Dismiss (close floating editor)
:w          Save file
Space f     File picker (fuzzy search)
Space /     Global search in project

From the terminal pane:

zellij edit -f filename       Open file in floating editor
zellij run -f -c -- hx .      Open Helix in floating pane

Helix Tutorial: Run hx --tutor for interactive tutorial

lazygit

j/k         Navigate up/down
Tab         Switch between panels
Space       Stage/unstage file or hunk
a           Stage/unstage all
c           Commit
P           Push (capital P)
p           Pull
?           Help menu
q           Quit

Documentation

After installation, a quick reference cheat sheet is available:

bat ~/.config/zellij/CHEATSHEET.md

Optional Configuration

Helix

Helix works great out of the box, but you can customize it if desired:

  1. Review helix/recommended-config.toml in this repo
  2. If you like the settings, copy to ~/.config/helix/config.toml
  3. Or merge with your existing config

Shell Aliases (Optional)

If you want convenience shortcuts, see shell/aliases-example.sh for suggestions. These are not installed automatically.

Why This Layout?

  • Claude-first - The AI conversation is the center of gravity, not the editor
  • Live diff review - lazygit with delta shows exactly what Claude changed, hunk by hunk
  • Interactive staging - Stage, discard, or revert individual lines from lazygit
  • Editor on demand - Pop up Helix as a floating overlay only when you need it
  • Session persistence - Detach/reattach without losing context

Workflow Examples

Starting a Feature

# 1. Start named session
cd ~/projects/myapp
zdev --session add-auth

# 2. Ask Claude to implement the feature (right pane)
# 3. Watch changes appear in lazygit (left top)
# 4. Review diffs interactively — stage hunks, discard bad ones
# 5. Run tests in terminal (left bottom)
# 6. Need to make a manual edit? Alt+e → Helix floats up → :q when done

# 7. Detach when done (Ctrl+g d)
# Everything keeps running!

# 8. Come back later
zellij attach add-auth

The AI-First Workflow

  1. Tell Claude what to build in the right pane
  2. Watch lazygit (left) — changes appear in real-time as Claude edits files
  3. Review diffs — lazygit shows syntax-highlighted, interactive diffs via delta
  4. Stage what's good — press Space on hunks, a to stage all
  5. Need a manual fix? — Alt+e to pop up Helix, edit, :q to dismiss
  6. Run commands in the terminal pane — tests, builds, dev servers
  7. Commit from lazygit when you're satisfied

Troubleshooting

Helix file picker not working

hx --health

Should show fd and rg in green. If not, run brew install fd ripgrep

Git delta not showing colors

git config --global --list | grep delta

Should show delta configuration. If not, run zdev config → Git Delta

Alt+e (floating editor) doesn't work (macOS)

On macOS, the Option key sends special characters instead of Alt by default. You need to configure your terminal to send Option as Meta:

Terminal Setting
iTerm2 Settings → Profiles → Keys → General → Left Option Key → Esc+
Ghostty Add macos-option-as-alt = left to ~/.config/ghostty/config
Kitty Add macos_option_as_alt left to ~/.config/kitty/kitty.conf
VSCode Add "terminal.integrated.macOptionIsMeta": true to settings.json

Run zdev config → Terminal to configure this automatically.

Note: This also fixes Zellij's built-in Alt+h/j/k/l navigation, Alt+n (new pane), and Alt+f (toggle floating).

lazygit fails in layout

If lazygit shows an error when launching the layout, you might not be in a git repository. Either:

  • cd to a git repo before launching Zellij
  • Or comment out the command "lazygit" line in the layout

Linting

./lint.sh          # Check all scripts (shellcheck) and markdown (prettier)
./lint.sh --fix    # Auto-format markdown in place

Requires shellcheck and Node.js (for prettier via npx). If either is missing, that check is skipped gracefully.

CI runs both checks automatically on PRs via GitHub Actions.

Contributing

Found an improvement? Open an issue or PR!

Credits

This setup was created with assistance from Claude Code, demonstrating how AI can help build better development environments.

License

MIT - Feel free to use, modify, and share!

About

An opinionated Zellij config for Claude Code

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages