Terminal Optimization

Terminal Optimization

Configure terminal environment for effective Claude Code usage.

Ghostty Configuration

Ghostty works well with Claude Code. Key settings:

# ~/.config/ghostty/config
font-family = JetBrains Mono
font-size = 14
window-padding-x = 10
window-padding-y = 10
cursor-style = bar
shell-integration = detect

See ghostty-config.md for full config.

Statusline

Display context usage and git info in shell prompt. Useful for:

• Tracking Claude Code context consumption
• Current git branch/status at a glance
• Session identification

See statusline-setup.md for starship/oh-my-zsh configs.

Voice Dictation

macOS: Press fn key twice to toggle dictation. Tips:

• Speak punctuation explicitly ("comma", "period", "new line")
• Pause briefly before/after commands
• Works in any text field including terminal

See voice-dictation.md for detailed tips.

Tab Naming

Name terminal tabs by project/task:

# Set tab title (most terminals)
echo -ne "\033]0;my-project\007"

# Or use terminal-specific shortcuts
# Ghostty: Cmd+Shift+I
# iTerm2: Cmd+I

tmux for Worktrees

Use tmux sessions per git worktree:

# Create session for worktree
tmux new-session -s feature-branch -c ~/repos/project-feature

# Attach to existing
tmux attach -t feature-branch

Each worktree gets isolated Claude Code context.

References

• ghostty-config.md - Full Ghostty configuration
• statusline-setup.md - Prompt/statusline setup
• voice-dictation.md - Voice input tips

Ghostty Configuration for Claude Code

Ghostty is a fast, GPU-accelerated terminal. Config location: ~/.config/ghostty/config

Recommended Config

# Font
font-family = JetBrains Mono
font-size = 14
font-thicken = true

# Window
window-padding-x = 10
window-padding-y = 10
window-decoration = true
window-theme = auto

# Cursor
cursor-style = bar
cursor-style-blink = false

# Shell integration
shell-integration = detect
shell-integration-features = cursor,sudo,title

# Clipboard
clipboard-read = allow
clipboard-write = allow
clipboard-paste-protection = false

# Performance
vsync = true
bold-is-bright = false

# Scrollback
scrollback-limit = 50000

# Tab bar
gtk-tabs-location = top
gtk-wide-tabs = false

Keybindings

# Split panes
keybind = ctrl+shift+d=new_split:right
keybind = ctrl+shift+s=new_split:down

# Navigate splits
keybind = ctrl+shift+h=goto_split:left
keybind = ctrl+shift+l=goto_split:right
keybind = ctrl+shift+j=goto_split:bottom
keybind = ctrl+shift+k=goto_split:top

# Tabs
keybind = cmd+t=new_tab
keybind = cmd+w=close_surface
keybind = cmd+shift+i=inspector:show

Theme Integration

Ghostty supports many themes. Set in config:

# Use a built-in theme
theme = catppuccin-mocha

# Or custom colors
background = 1e1e2e
foreground = cdd6f4
selection-background = 45475a
selection-foreground = cdd6f4

Claude Code Tips

1. Large scrollback - Set scrollback-limit = 50000 for long Claude outputs 2. No paste protection - clipboard-paste-protection = false avoids prompts 3. Shell integration - Enables better prompt detection for context

Troubleshooting

Font rendering issues

font-thicken = true
freetype-load-flags = no-hinting

Slow startup

Check for slow shell initialization in .zshrc or .bashrc.

Copy/paste not working

Ensure clipboard settings are enabled and no conflicting keybindings.

Statusline Setup

Display context usage, git branch, and session info in shell prompt.

Starship Configuration

Starship is cross-shell. Config: ~/.config/starship.toml

Basic Setup

format = """
$directory$git_branch$git_status$character"""

[directory]
truncation_length = 3
truncate_to_repo = true

[git_branch]
format = "[$branch]($style) "
style = "bold purple"

[git_status]
format = '([$all_status$ahead_behind]($style) )'
style = "bold red"

[character]
success_symbol = "[>](bold green)"
error_symbol = "[>](bold red)"

With Claude Context Display

Add custom command to show context:

[custom.claude_context]
command = "claude context 2>/dev/null | grep -o '[0-9]*%' | head -1 || echo ''"
when = "command -v claude"
format = "[$output]($style) "
style = "bold cyan"

Oh-My-Zsh

Git Plugin (built-in)

Add to ~/.zshrc:

plugins=(git)

Provides: git_current_branch, git_prompt_info

Custom Prompt with Context

# Add to ~/.zshrc
claude_context() {
  local ctx=$(claude context 2>/dev/null | grep -o '[0-9]*%' | head -1)
  [[ -n "$ctx" ]] && echo "[ctx:$ctx] "
}

PROMPT='$(claude_context)%F{cyan}%~%f %F{magenta}$(git_current_branch)%f > '

Pure Bash

# Add to ~/.bashrc
parse_git_branch() {
  git branch 2>/dev/null | grep '^*' | cut -d' ' -f2
}

claude_ctx() {
  local ctx=$(claude context 2>/dev/null | grep -o '[0-9]*%' | head -1)
  [[ -n "$ctx" ]] && echo "[ctx:$ctx] "
}

PS1='$(claude_ctx)\[\033[36m\]\w\[\033[35m\] $(parse_git_branch)\[\033[0m\] > '

Context Tracking Tips

1. Check periodically - Run claude context to see usage 2. Start fresh - Use /clear when context gets high 3. Color code - Change prompt color when context > 80%

Auto-warning

# Warn when context high
check_context() {
  local pct=$(claude context 2>/dev/null | grep -o '[0-9]*' | head -1)
  [[ "$pct" -gt 80 ]] && echo -e "\033[33m[!] Claude context at ${pct}%\033[0m"
}
PROMPT_COMMAND="check_context; $PROMPT_COMMAND"

Session Identification

Name sessions for multi-project work:

# Set window/tab title
set_title() { echo -ne "\033]0;$1\007"; }

# Auto-set from git repo
auto_title() {
  local repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null)
  [[ -n "$repo" ]] && set_title "$repo"
}
cd() { builtin cd "$@" && auto_title; }

Voice Dictation Tips

Use voice input for faster prompting. Works in any text field including terminal.

macOS Dictation

Enable

System Settings > Keyboard > Dictation > On

Trigger

Press fn key twice to toggle dictation on/off.

Punctuation Commands

Speak these to insert punctuation:

Formatting Commands

Best Practices

For Claude Code Prompts

1. Pause before starting - Let dictation fully activate 2. Speak clearly - Moderate pace, don't rush 3. State punctuation - "Fix the bug in auth dot ts comma then run tests" 4. Use "new line" - For multi-step instructions

Example Dictated Prompt

Speak: "Fix the login function in auth dot ts new line Add error handling for invalid tokens new line Then run the test suite period"

Result:

Fix the login function in auth.ts
Add error handling for invalid tokens
Then run the test suite.

Troubleshooting

Dictation not starting

• Check microphone permissions
• Restart dictation in System Settings
• Try "Enhanced Dictation" for offline mode

Wrong words transcribed

• Speak more slowly
• Ensure quiet environment
• Add custom words to macOS dictionary

Stops unexpectedly

• macOS auto-stops after pause
• Say something or press fn twice to restart

Keyboard Shortcuts

Customize the trigger key in System Settings > Keyboard > Dictation > Shortcut.

Options:

• Press fn Key Twice (default)
• Press Left Command Key Twice
• Press Either Command Key Twice
• Press Right Command Key Twice

Terminal-Specific Notes

1. Cursor position matters - Dictation inserts at cursor 2. No auto-submit - Still need to press Enter 3. Editing - Use keyboard to correct, then continue dictating 4. Long prompts - Dictation is great for detailed instructions

Linux Alternative

Use speech-to-text tools:

• Whisper (OpenAI) with whisper.cpp
• Nerd Dictation
• Google Cloud Speech API

Setup varies by distro. Typically requires hotkey daemon.