🚀 macOS Development Setup

Complete, automated setup for macOS development environments. Get up and running with essential dev tools, a beautiful terminal, tmux workflow, and a live Claude Code monitoring dashboard.

✨ What This Does

This repository provides automated scripts to set up a complete development environment on macOS, including:

🛠️ Development Tools

Homebrew - Package manager for macOS
Git - Version control
Python 3.11 with pyenv - Python version management
Node.js & npm - JavaScript runtime and package manager
Common utilities - tree, jq, wget, curl, htop

🎨 Terminal Customization

Oh My Zsh - Powerful zsh framework
Powerlevel10k - Beautiful terminal theme
zsh plugins - Autosuggestions, syntax highlighting, and more
Modern CLI tools - eza, bat, fzf, fd, thefuck

🖥️ Terminal Multiplexer (tmux)

tmux with Catppuccin Mocha theme
TPM - Tmux Plugin Manager
tmux-resurrect & tmux-continuum - Session persistence
btop - Beautiful system monitor
dev-session - Pre-configured Claude Code workflow layout

📊 Claude Code Monitor

Live TUI dashboard for tracking Claude Code CLI instances
Active instance tracking (PID, CPU%, uptime, project)
Today's message/session counts
Lifetime token usage by model (auto-scanned from session files)
Session & message history with active days count
Recent activity feed with timestamps
Works out of the box — no config needed, reads directly from ~/.claude/
Catppuccin Mocha colors, flicker-free 5s refresh via rich

🚀 Quick Start

One-Command Setup

./setup-macos.sh

This launches an interactive menu:

Full Setup - Dev tools + Terminal + tmux
Dev Environment Only - Essential development tools
Terminal Only - Terminal beautification
Multiplexer Only - tmux with Catppuccin theme + dev sessions
Claude Monitor - Live dashboard for Claude Code instances
Verify Setup - Check what's already installed
Exit

📋 Prerequisites

macOS 11.0 or later
Terminal with zsh (default on modern macOS)
Internet connection
Admin privileges (for Homebrew installation)

📁 Repository Structure

MacDev/
├── setup-macos.sh                # Main entry point (interactive menu)
├── scripts/                      # Core setup scripts
│   ├── setup-dev-env.sh         # Development environment installer
│   ├── pimp-my-terminal.sh      # Terminal customization installer
│   ├── setup-tmux.sh            # tmux + theme + plugins installer
│   ├── setup-claude-monitor.sh  # Claude Code Monitor installer
│   ├── claude-monitor.py        # Live dashboard (rich TUI)
│   └── verify-setup.sh          # Verification script
├── configs/                      # Configuration files
│   ├── tmux.conf                # tmux config (Catppuccin Mocha theme)
│   └── dev-session.sh           # Dev session layout launcher
├── docs/                         # Documentation
│   ├── DEV_ENVIRONMENT_GUIDE.md
│   └── TERMINAL_SETUP_GUIDE.md
└── examples/                     # Project-specific examples
    ├── start_dev.sh
    ├── verify_setup_project.sh
    └── README.md

📖 Detailed Usage

Development Environment

./scripts/setup-dev-env.sh

Installs Homebrew, Git, Python 3.11 (via pyenv), Node.js & npm, and common utilities.

Terminal Customization

./scripts/pimp-my-terminal.sh

Installs Oh My Zsh, Powerlevel10k, zsh plugins, and modern CLI tools (eza, bat, fzf, fd, thefuck).

tmux Multiplexer

./scripts/setup-tmux.sh

Installs tmux with Catppuccin Mocha theme, TPM, session persistence plugins, btop, and the dev-session command for a Claude Code workflow layout.

Claude Code Monitor

./scripts/setup-claude-monitor.sh

Installs the live monitoring dashboard. Requires uv (auto-installed via Homebrew/installer).

Usage after install:

claude-monitor          # Live dashboard (5s refresh)
claude-monitor --once   # Single snapshot
claude-monitor -i 10    # Custom refresh interval
claude-monitor --compact # Compact mode for small tmux panes
cmon                    # Alias for claude-monitor

Dashboard shows:

╭──────────────────────── CLAUDE CODE MONITOR ─────────────────────────╮
│  ● 2 active instances                                                │
│  MacDev       PID 76988  CPU 11.9%   33m                             │
│  myproject    PID 23919  CPU 0.4%    2d 21h                          │
│                                                                      │
│  TODAY  Mar 14                                                       │
│  Messages █░░░░░░░░░░░░░░  9                                         │
│  Sessions ███░░░░░░░░░░░░  2                                         │
│                                                                      │
│  TOKENS (lifetime)                                                   │
│  opus-4-6           97M tokens                                       │
│                                                                      │
│  RECENT                                                              │
│  18:49 MacDev     fix the login bug                                  │
│  18:47 myproject  add dark mode support                              │
│                                                                      │
│  LIFETIME  8 sessions · 43 msgs · 7 active days                      │
│  Since Feb 26, 2026                                                  │
╰──────────────────────────── ↻ 18:50:09 ──────────────────────────────╯

Where does the data come from?

The monitor reads directly from Claude Code's local files — no API keys or config needed:

Data	Source
Active instances	`ps` + `lsof` (running `claude` processes)
Today's messages/sessions	`~/.claude/history.jsonl`
Token usage per model	`~/.claude/projects//.jsonl` (session files)
Lifetime stats	`~/.claude/history.jsonl` (all entries)
Recent activity	`~/.claude/history.jsonl` (last 5 entries)

If ~/.claude/stats-cache.json exists (some Claude Code versions generate it), the monitor uses that too for enriched stats.

Dev Session (tmux layout)

cd ~/projects/myapp
sc                    # that's it - launches everything

# also works as:
dev-session                              # same as sc, uses current dir
dev-session ~/projects/myapp             # give it a path
dev-session myapp ~/projects/myapp       # explicit name + path
dev-session --monitor=btop               # override system monitor

Creates a tmux layout optimized for Claude Code:

┌────────────────────────┬──────────────────┐
│                        │   Dev Server     │
│    Claude Code         │   (npm run dev)  │
│    (80% height)        ├──────────────────┤
│                        │   System Monitor │
├────────────────────────┤   (btop)         │
│    Claude Monitor      │                  │
│    (20% height)        │                  │
└────────────────────────┴──────────────────┘
        65% width              35% width

Bottom-left: Claude Monitor always runs here (live dashboard)
Bottom-right: System monitor (btop > htop > top, or --monitor=CMD)

Verify Setup

./scripts/verify-setup.sh

Checks all installed components including dev tools, terminal enhancements, tmux, and Claude Monitor.

🎯 What You Get

Terminal Features

ll                  # Beautiful file listing with icons
cat file.py         # Syntax highlighting with bat
Ctrl+R              # Fuzzy search command history
Ctrl+T              # Find files
gs                  # git status
fuck                # Fix your last command

tmux Keybindings (prefix = Ctrl+a)

Key	Action
`Ctrl+a \|`	Split pane vertically
`Ctrl+a -`	Split pane horizontally
`Alt+arrows`	Navigate between panes
`Shift+arrows`	Switch between windows
`Ctrl+a z`	Zoom/unzoom current pane
`Ctrl+a d`	Detach from session
`Ctrl+a I`	Install plugins (capital I)

🔧 Customization

Configure Terminal Theme

p10k configure

Edit Shell Configuration

nano ~/.zshrc
source ~/.zshrc

🐛 Troubleshooting

Homebrew not found

eval "$(/opt/homebrew/bin/brew shellenv)"

Icons not showing in terminal

Install a Nerd Font (Powerlevel10k wizard will help).

Command not found after installation

source ~/.zshrc

uv cache permission error

If claude-monitor fails with a permission error on ~/.cache/uv:

sudo chown -R $(whoami) ~/.cache/uv

🌟 Features

✅ Idempotent - Safe to run multiple times
✅ Backs up your existing configuration
✅ Modular - Use only what you need
✅ Error handling - Stops on failures
✅ Colorful output - Easy to follow progress
✅ Zero-setup dependencies - uv run handles Python packages automatically

🙏 Credits

This setup installs and configures these open-source projects:

Ready to pimp your development environment? Let's go! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
configs		configs
docs		docs
examples		examples
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
QUICK_START.md		QUICK_START.md
README.md		README.md
STRUCTURE.md		STRUCTURE.md
SUMMARY.md		SUMMARY.md
setup-macos.sh		setup-macos.sh

Folders and files

Latest commit

History

Repository files navigation

🚀 macOS Development Setup

✨ What This Does

🛠️ Development Tools

🎨 Terminal Customization

🖥️ Terminal Multiplexer (tmux)

📊 Claude Code Monitor

🚀 Quick Start

One-Command Setup

📋 Prerequisites

📁 Repository Structure

📖 Detailed Usage

Development Environment

Terminal Customization

tmux Multiplexer

Claude Code Monitor

Dev Session (tmux layout)

Verify Setup

🎯 What You Get

Terminal Features

tmux Keybindings (prefix = Ctrl+a)

🔧 Customization

Configure Terminal Theme

Edit Shell Configuration

🐛 Troubleshooting

Homebrew not found

Icons not showing in terminal

Command not found after installation

uv cache permission error

🌟 Features

🙏 Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages