GitHubHelp

shivi28/claude-code-iterm-split

★ 0Forks 0ShellGitHub ↗Compare

README

short — Claude Code + shell, side by side in iTerm2

A single command, short, that opens an iTerm2 window split into two panes — a normal shell on one side and Claude Code on the other, both opened in your current directory:

┌──────────────┬───────────────────────────────┐
│  shell (30%) │  Claude Code (70%)            │
│              │  • light, claude.ai-style     │
│  your normal │    background                 │
│  dark prompt │  • dark, readable text        │
│              │                               │
└──────────────┴───────────────────────────────┘
  • short → side-by-side: shell 30% left, Claude 70% right
  • short --h → stacked: shell 30% top, Claude 70% bottom

The Claude pane gets a light, claude.ai-style warm-white background; the shell pane keeps your existing Default profile look exactly.

Why a light Claude pane "just works"

Claude Code auto-detects light vs. dark from the terminal background at startup. This setup gives the Claude pane a light background from the very first frame (via a dedicated iTerm2 profile), so Claude picks its light theme — crisp dark text on warm white — automatically. No Claude config change required.

Requirements

  • macOS
  • iTerm2 (the split/scripting features use iTerm2's AppleScript dictionary; macOS Terminal.app won't work)
  • Claude Code on your PATH (claude)
  • zsh (the default shell on modern macOS)

Install

git clone <this-repo> claude-code-iterm-split
cd claude-code-iterm-split
./install.sh

The installer:

  1. Copies short-pane and a generated short.scpt into ~/bin.
  2. Reads your real Default profile colors and bakes them into the shell pane, so it matches your normal terminal (not hardcoded to anyone else's).
  3. Installs the light "Claude" profile into iTerm2's DynamicProfiles.
  4. Adds the short function to your ~/.zshrc (inside clearly marked begin/end markers, so re-running stays clean).

Then, as the installer prints:

  1. Quit and reopen iTerm2 once so it loads the new "Claude" profile.
  2. source ~/.zshrc

Now cd into any project and run short.

How it works

Piece What it does
~/.zshrc short() Base64-encodes $PWD (space-safe) and calls the AppleScript.
~/bin/short.scpt Opens the iTerm2 window, splits it, sizes the panes 30/70, and runs the per-pane helper.
~/bin/short-pane Per-pane script: decodes the dir, cds into it, and (right pane) launches claude. Runs as a login shell so claude is on PATH.
iterm/Claude.json A light iTerm2 profile that inherits your Default profile and overrides only the colors.

A couple of non-obvious details that make it smooth:

  • The directory is passed base64-encoded because iTerm runs a pane's start command via execvp (no shell), so spaces in a path would otherwise be split into separate arguments and break cd.
  • The Claude profile uses "Dynamic Profile Parent Name": "Default" so it inherits your font, transparency, padding, etc. — only the background / foreground / cursor colors are overridden. (A standalone profile would reset all those to iTerm defaults and look "blurry/wrong".)

Customizing

Claude pane background / colors — edit ~/Library/Application Support/iTerm2/DynamicProfiles/claude-short.json. Color components are 0.0–1.0. The default is a warm white #FAF8F2 with a terracotta cursor. Save the file and iTerm reloads it automatically.

Split ratio — edit ~/bin/short.scpt and change * 0.3 (the shell pane's share) to taste, e.g. * 0.25 for a narrower shell.

Force Claude's theme (optional) — auto-detection is enough, but if you want to pin it, set "theme": "light" (or "dark") in ~/.claude/settings.json.

Default profile not named "Default"? — edit the "Dynamic Profile Parent Name" value in claude-short.json to match your profile's name.

Uninstall

./uninstall.sh

Removes ~/bin/short.scpt, ~/bin/short-pane, the iTerm profile, and the short() block from ~/.zshrc.

License

MIT — see LICENSE.

Contributors

shivi28

Issues