Developer Environment
Recommended shell, terminal, and tooling setup for working on Roxabi
Overview
Note: This guide is opinionated toward a Windows + WSL2 setup (WezTerm, tmux, zsh). If you're on macOS or native Linux, the core requirements are the same (Bun, Node.js, PostgreSQL) — feel free to substitute your preferred terminal and shell.
This guide documents the recommended developer environment for working on Roxabi. It covers shell configuration, terminal emulator, tmux, and CLI tooling.
The project runs on WSL2 (Ubuntu) with Bun as the primary runtime.
Prerequisites
| Tool | Version | Install |
|---|---|---|
| Bun | >= 1.3 | curl -fsSL https://bun.sh/install | bash |
| Node.js | >= 24 | Via nvm |
| Git | Latest | sudo apt install git |
| Docker | Latest | Docker Desktop for WSL2 |
| Starship | Latest | curl -sS https://starship.rs/install.sh | sh |
| WezTerm | Latest | Windows installer (connects to WSL2) |
| tmux | >= 3.3 | sudo apt install tmux |
| Claude Code | Latest | npm install -g @anthropic-ai/claude-code |
Shell (Bash)
~/.bashrc
Key additions to append at the end of ~/.bashrc:
# bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
# nvm (if using nvm for Node.js)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
# local binaries
export PATH="$HOME/.local/bin:$PATH"
# Claude Code agent teams (experimental)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# starship prompt (must be last)
eval "$(starship init bash)"~/.bash_aliases
Project-specific aliases in a separate file (sourced by .bashrc):
# Navigation
alias cdb='cd ~/projects/roxabi_boilerplate; clear'
# Claude Code
alias cc='claude'
alias ccc='claude --dangerously-skip-permissions'
alias ccusage='npx ccusage@latest'
# Agent-specific sessions
alias cc-front='claude --agent frontend-dev'
alias cc-back='claude --agent backend-dev'
alias cc-test='claude --agent tester'
alias cc-pa='claude --agent product-lead'Tip: Keep aliases in
~/.bash_aliasesrather than.bashrc— it keeps things organized and.bashrcsources it automatically on Ubuntu.
Tmux
~/.tmux.conf
set -g default-terminal "tmux-256color"
set -g mouse on
set -g set-titles on
set -g set-titles-string "#{pane_title}"
set -g allow-passthrough on
set -s set-clipboard on
set -s extended-keys always
set -as terminal-features 'xterm*:extkeys'
set -as terminal-features 'xterm*:hyperlinks'
set -s extended-keys-format csi-u
# Middle-click paste from Windows clipboard
bind -n MouseDown2Pane run -b 'tmux set-buffer -- "$(powershell.exe -command Get-Clipboard | tr -d \\r)"; tmux paste-buffer -p'| Setting | Purpose |
|---|---|
default-terminal | Set terminal type to tmux-256color for correct capability detection |
mouse on | Scroll, resize panes, and select windows with mouse |
set-titles on | Propagate pane titles to the terminal emulator |
set-titles-string | Format for the terminal title (uses pane title) |
allow-passthrough on | Let applications (Claude Code, Neovim, etc.) set the terminal title directly via escape sequences. Requires tmux >= 3.3 |
set-clipboard on | Enable OSC 52 clipboard integration |
extended-keys / csi-u | Kitty keyboard protocol support (matches WezTerm's enable_kitty_keyboard) |
terminal-features | Enable extended keys and hyperlink detection for xterm-compatible terminals |
| Middle-click paste | Paste from Windows clipboard via PowerShell (WSL-specific) |
Reload config
tmux source-file ~/.tmux.confUseful tmux shortcuts
| Shortcut | Action |
|---|---|
Ctrl-b c | New window |
Ctrl-b , | Rename window |
Ctrl-b % | Split pane vertically |
Ctrl-b " | Split pane horizontally |
Ctrl-b d | Detach session |
Ctrl-b [ | Scroll mode (q to exit) |
WezTerm
WezTerm is a GPU-accelerated terminal emulator with first-class WSL2 support. It runs on Windows and connects to your WSL2 environment.
Configuration
WezTerm uses a Lua config file. Create ~/.wezterm.lua (in your Windows home, e.g. C:\Users\<name>\.wezterm.lua):
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
-- Default to WSL2
config.default_domain = 'WSL:Ubuntu'
-- Font
config.font = wezterm.font('JetBrains Mono')
config.font_size = 11.0
-- Tab bar
config.use_fancy_tab_bar = false
config.hide_tab_bar_if_only_one_tab = true
-- Window
config.window_padding = { left = 4, right = 4, top = 4, bottom = 4 }
return configNote: Customize font, colors, and keybindings to your preference. See the WezTerm docs for all options.
Tab titles with tmux
If WezTerm tab titles don't update inside tmux, ensure your ~/.tmux.conf includes:
set -g set-titles on
set -g set-titles-string "#{pane_title}"
set -g allow-passthrough on
set -s extended-keys always
set -as terminal-features 'xterm*:extkeys'
set -s extended-keys-format csi-uClaude Code
Installation
npm install -g @anthropic-ai/claude-codeUseful aliases
alias cc='claude' # Quick launch
alias ccc='claude --dangerously-skip-permissions' # Skip permission prompts (use with caution)
alias ccusage='npx ccusage@latest' # Check API usage
# Agent-specific sessions (run as a specific agent role)
alias cc-front='claude --agent frontend-dev' # Frontend-focused session
alias cc-back='claude --agent backend-dev' # Backend-focused session
alias cc-test='claude --agent tester' # Testing-focused session
alias cc-pa='claude --agent product-lead' # Product lead session--agent flag
Start Claude Code as a pre-defined agent. The main conversation uses the agent's system prompt, tools, and permissions:
claude --agent backend-dev # Use agent from .claude/agents/backend-dev.md
claude --agent my-agent # Use agent from ~/.claude/agents/my-agent.mdSee Agent Teams Guide for details on --agent vs --agents and all session modes.
Agent teams
Enable experimental multi-agent coordination by exporting in ~/.bashrc:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1See Agent Teams Guide for details on available agents and coordination patterns.
Hooks
Claude Code hooks (auto-format, typecheck, security warnings) are configured in .claude/settings.json — no manual setup needed. See Hooks for details.
Starship Prompt
Starship provides a fast, customizable prompt that shows git branch, Node/Bun versions, and more.
Installation
curl -sS https://starship.rs/install.sh | shAdd to the end of ~/.bashrc:
eval "$(starship init bash)"Configuration
Create ~/.config/starship.toml to customize. Example minimal config:
[character]
success_symbol = "[>](bold green)"
error_symbol = "[>](bold red)"
[git_branch]
symbol = " "
[bun]
symbol = " "
[nodejs]
symbol = " "See the Starship docs for all modules.
Quick Setup Checklist
For a fresh WSL2 Ubuntu installation:
# 1. Install system packages
sudo apt update && sudo apt install -y git tmux build-essential
# 2. Install Bun
curl -fsSL https://bun.sh/install | bash
# 3. Install nvm + Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 24
# 4. Install Starship
curl -sS https://starship.rs/install.sh | sh
# 5. Install Claude Code
npm install -g @anthropic-ai/claude-code
# 6. Configure tmux
cat >> ~/.tmux.conf << 'EOF'
set -g default-terminal "tmux-256color"
set -g mouse on
set -g set-titles on
set -g set-titles-string "#{pane_title}"
set -g allow-passthrough on
set -s set-clipboard on
set -s extended-keys always
set -as terminal-features 'xterm*:extkeys'
set -as terminal-features 'xterm*:hyperlinks'
set -s extended-keys-format csi-u
bind -n MouseDown2Pane run -b 'tmux set-buffer -- "$(powershell.exe -command Get-Clipboard | tr -d \\r)"; tmux paste-buffer -p'
EOF
# 7. Configure aliases
cat >> ~/.bash_aliases << 'EOF'
alias cdb='cd ~/projects/roxabi_boilerplate; clear'
alias cc='claude'
alias ccc='claude --dangerously-skip-permissions'
alias ccusage='npx ccusage@latest'
alias cc-front='claude --agent frontend-dev'
alias cc-back='claude --agent backend-dev'
alias cc-test='claude --agent tester'
alias cc-pa='claude --agent product-lead'
EOF
# 8. Add to ~/.bashrc (if not already present)
echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.bashrc
# 9. Clone and install
git clone <repo-url> ~/projects/roxabi_boilerplate
cd ~/projects/roxabi_boilerplate
bun install
# 10. Reload shell
source ~/.bashrcAfter this, install WezTerm on Windows and configure ~/.wezterm.lua as shown above.