By Avinash, GenAI Practice Lead
⚠️ Note: This setup is macOS-specific. All tools, commands, and configurations in this series are tested on macOS (Apple Silicon). Linux and Windows users will need to adapt certain steps, particularly around
afplay,brew, iTerm2, and system font installation.
I lead a GenAI practice and manage a broad portfolio of active AI projects. A significant part of my day is spent inside Claude Code — building model evaluation frameworks, debugging pipelines, writing architecture documents, and reviewing code with my team. Claude Code is genuinely powerful, but after weeks of daily use I kept running into the same friction points.
Sessions started completely blind every time. No memory of what we built yesterday, no context on decisions made last week. I'd spend the first 10 minutes of every session re-establishing context that Claude had already processed the day before.
There was no visibility into token usage or cost while working. I'd hit a rate limit mid-task with no warning, losing momentum at the worst possible moment. On a Pro plan where every token has a cost, flying blind is expensive.
Claude finishing a task while I was context-switched elsewhere meant I'd come back 5 minutes later to find it waiting. No notification, no signal — just a blinking cursor.
And the terminal itself was a plain, low-information environment. No git context, no Python version, no time — just a prompt.
These aren't complaints about Claude Code. They're gaps in the surrounding environment that any developer can close with the right setup. So I spent a day closing them.
What I Built
Over a focused session I assembled a complete terminal environment optimised specifically for Claude Code development on macOS. Here's the full stack:
Claude Code layer:
- Custom bash statusline showing model, git branch, token usage, cost, context %, and rate limit countdowns
- Sound notification hooks using macOS
afplayfor task completion, permission requests, and idle state - 9 curated plugins covering code review, persistent memory, Python type checking, and workflow automation
Terminal layer:
- iTerm2 with tokyo-night color theme and JetBrains Mono Nerd Font
- tmux with a 3-pane layout and session persistence across restarts
- Starship prompt with tokyo-night preset showing git status and Python version
- fzf for fuzzy command history search
- zsh-autosuggestions and zsh-syntax-highlighting
Everything is committed to a dotfiles repo at https://github.com/ai-with-avinash/claude-code-best-setup with a fresh machine checklist so the entire setup can be reproduced on a new Mac in under an hour.
The Series
This is Part 1 of 6. Each subsequent article covers one layer of the setup in detail:
- Part 2 — Custom Statusline: real-time token, cost, and rate limit visibility
- Part 3 — Sound Notification Hooks: knowing when Claude is done without watching the screen
- Part 4 — Plugin Stack: 9 plugins that earn their place and what I removed
- Part 5 — Terminal Environment: iTerm2, tmux, starship, fzf, and zsh
- Part 6 — Dotfiles Repo: packaging everything for reproducibility
Each part is self-contained — you can read them in any order depending on what's most relevant to your setup. But if you're starting fresh, the sequence matters and Part 2 is where I'd begin.
Top comments (0)