# Terminal Setup

> Claude Code works best when your terminal is properly configured. Follow these guidelines to optimize your experience.

## Themes and Appearance

Claude cannot control the theme of your terminal. That's handled by your terminal application. You can match Claude Code's theme to your terminal any time via the `/config` command.

For additional customization of the Claude Code interface itself, you can configure a custom status line to display contextual information like the current model, working directory, or git branch at the bottom of your terminal.

## Line Breaks

You have several options for entering line breaks into Claude Code:

- **Quick escape**: Type `\` followed by Enter to create a newline
- **Shift+Enter**: Works out of the box in iTerm2, WezTerm, Ghostty, and Kitty
- **Keyboard shortcut**: Set up a keybinding to insert a newline in other terminals

### Set up Shift+Enter for Other Terminals

Run `/terminal-setup` within Claude Code to automatically configure Shift+Enter for VS Code, Alacritty, Zed, and Warp.

**Note**: The `/terminal-setup` command is only visible in terminals that require manual configuration.

### Set up Option+Enter (VS Code, iTerm2 or macOS Terminal.app)

**For Mac Terminal.app:**
1. Open Settings -> Profiles -> Keyboard
2. Check "Use Option as Meta Key"

**For iTerm2 and VS Code terminal:**
1. Open Settings -> Profiles -> Keys
2. Under General, set Left/Right Option key to "Esc+"

## Notification Setup

Never miss when Claude completes a task with proper notification configuration.

### iTerm 2 System Notifications

1. Open iTerm 2 Preferences
2. Navigate to Profiles -> Terminal
3. Enable "Silence bell" and Filter Alerts -> "Send escape sequence-generated alerts"
4. Set your preferred notification delay

**Note**: These notifications are specific to iTerm 2 and not available in the default macOS Terminal.

### Custom Notification Hooks

For advanced notification handling, you can create notification hooks:

```json
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

## Handling Large Inputs

When working with extensive code or long instructions:

- **Avoid direct pasting**: Claude Code may struggle with very long pasted content
- **Use file-based workflows**: Write content to a file and ask Claude to read it
- **Be aware of VS Code limitations**: The VS Code terminal is particularly prone to truncating long pastes

## Vim Mode

Claude Code supports a subset of Vim keybindings that can be enabled with `/vim` or configured via `/config`.

The supported subset includes:

- **Mode switching**: `Esc` (to NORMAL), `i`/`I`, `a`/`A`, `o`/`O` (to INSERT)
- **Navigation**: `h`/`j`/`k`/`l`, `w`/`e`/`b`, `0`/`$`, `^`, `gg`/`G`
- **Editing**: `x`, `dd`, `D`, `cc`, `C`, `yy`, `p`/`P`
- **Visual mode**: `v` for character-wise selection
- **Search**: `/` to search, `n`/`N` for next/previous match
- **Undo/Redo**: `u` to undo

## Status Line Configuration

Create a custom status line that displays at the bottom of the Claude Code interface:

### Basic Setup

Add to `.claude/settings.json`:
```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}
```

Or run `/statusline` to have Claude Code help you set one up.

### How It Works

- The status line is updated when conversation messages update
- Updates run at most every 300 ms
- The first line of stdout from your command becomes the status line text
- ANSI color codes are supported for styling
- Claude Code passes contextual information as JSON via stdin

### JSON Input Structure

Your status line command receives:
```json
{
  "hook_event_name": "Status",
  "session_id": "abc123...",
  "cwd": "/current/working/directory",
  "model": {
    "id": "claude-opus-4-1",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/current/working/directory",
    "project_dir": "/original/project/directory"
  },
  "version": "1.0.80",
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000
  },
  "context_window": {
    "total_input_tokens": 15234,
    "used_percentage": 42.5
  }
}
```

### Example: Simple Status Line

```bash
#!/bin/bash
input=$(cat)
MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
echo "[$MODEL_DISPLAY] ${CURRENT_DIR##*/}"
```

### Example: Git-Aware Status Line

```bash
#!/bin/bash
input=$(cat)
MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')

GIT_BRANCH=""
if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    if [ -n "$BRANCH" ]; then
        GIT_BRANCH=" | $BRANCH"
    fi
fi

echo "[$MODEL_DISPLAY] ${CURRENT_DIR##*/}$GIT_BRANCH"
```

## Recommended Terminal Emulators

For the best Claude Code experience:

- **iTerm2** (macOS) - Best native support for Shift+Enter and notifications
- **WezTerm** - Cross-platform with excellent keybinding support
- **Ghostty** - Modern, fast terminal with native Shift+Enter
- **Kitty** - GPU-accelerated with good configuration options
- **Alacritty** - Fast, minimal (requires `/terminal-setup`)

## Grid Integration Opportunities

<!-- Placeholder for Grid-specific integration notes -->