Merge pull request #35 from alanbem/feat/iterm2-shell-integration

feat: add iTerm2 shell integration

Author: alanbem

.hadolint.yaml

@@ -13,6 +13,9 @@ ignored:
   # Entrypoint starts as root for permission setup, then uses gosu to switch to claude user
   - DL3002  # Last USER should not be root
 
+  # Single quotes are intentional - expressions should expand at runtime, not build time
+  - SC2016  # Expressions don't expand in single quotes
+
 trustedRegistries:
   - docker.io
   - ghcr.io

CLAUDE.md

@@ -593,6 +593,50 @@ set-option -g detach-on-destroy on
 - The `detect_tty_flags()` function returns `-i -t` flags for interactive mode, empty for non-interactive
 - The `is_print_mode()` function checks for `-p`/`--print` as separate arguments (safe from string matching)
 
+## iTerm2 Shell Integration
+
+dclaude includes [iTerm2 Shell Integration](https://iterm2.com/documentation-shell-integration.html) for enhanced terminal experience on macOS.
+
+### How It Works
+
+**Automatic activation:**
+- Script baked into image at `/home/claude/.iterm2_shell_integration.bash`
+- Sourced in `~/.bashrc` with opt-out check
+- Only activates for interactive shells in iTerm2 (script self-checks environment)
+- Works inside tmux via `ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=1` env var
+
+**Features enabled:**
+- URL handling (click URLs to open in Mac browser)
+- `imgcat` command (display images inline)
+- `it2copy` command (copy to Mac clipboard)
+- Shell marks (navigate between prompts)
+- Command status tracking
+
+### Configuration
+
+**Opt-out:**
+```bash
+DCLAUDE_ITERM2=false dclaude
+```
+
+**Environment variables:**
+- `DCLAUDE_ITERM2` - Set to `false` to disable (default: `true`)
+- `ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX` - Set by dclaude to enable in tmux sessions
+
+### Technical Details
+
+**Script location:** `/home/claude/.iterm2_shell_integration.bash` (baked into image)
+
+**Bashrc sourcing:**
+```bash
+[[ "${DCLAUDE_ITERM2:-true}" != "false" && -f ~/.iterm2_shell_integration.bash ]] && source ~/.iterm2_shell_integration.bash
+```
+
+**Why tmux requires special handling:**
+The iTerm2 script by default skips tmux sessions (checks `$TERM` for `screen` or `tmux-256color`). Setting `ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=1` bypasses this check, allowing integration to work inside dclaude's tmux-managed sessions.
+
+**Non-iTerm2 terminals:** The script is safe for other terminals - it checks the environment and does nothing if iTerm2 isn't detected.
+
 ## Chrome DevTools Integration
 
 The `dclaude chrome` subcommand provides seamless integration between Claude and Chrome DevTools via the Model Context Protocol (MCP).

README.md

@@ -151,6 +151,21 @@ dclaude chrome                    # Launch Chrome with DevTools
 dclaude                           # Claude can now interact with the browser
 ```
 
+### iTerm2 Shell Integration
+
+If you use iTerm2 on macOS, dclaude automatically enables [iTerm2 Shell Integration](https://iterm2.com/documentation-shell-integration.html):
+
+- **Click URLs in output** - Opens in your Mac's browser
+- **imgcat** - Display images inline in terminal
+- **it2copy** - Copy to Mac clipboard from inside container
+- **Marks** - Navigate between command prompts
+
+This only activates when running in iTerm2. To disable:
+
+```bash
+DCLAUDE_ITERM2=false dclaude
+```
+
 ### System Context
 
 dclaude automatically tells Claude about its container environment so it can give better suggestions:
@@ -180,6 +195,7 @@ DCLAUDE_SYSTEM_CONTEXT=false dclaude
 | `DCLAUDE_QUIET` | `false` | Suppress info messages |
 | `DCLAUDE_NO_UPDATE` | `false` | Skip image update check |
 | `DCLAUDE_SYSTEM_CONTEXT` | `true` | Inform Claude about container environment |
+| `DCLAUDE_ITERM2` | `true` | Enable iTerm2 shell integration (only affects iTerm2) |
 
 ## Configuration File
 

dclaude

@@ -1242,6 +1242,7 @@ main() {
                 [[ -n "${TERM_PROGRAM_VERSION:-}" ]] && exec_env_args+=(-e "TERM_PROGRAM_VERSION=${TERM_PROGRAM_VERSION}")
                 [[ -n "${TERM_SESSION_ID:-}" ]] && exec_env_args+=(-e "TERM_SESSION_ID=${TERM_SESSION_ID}")
                 [[ -n "${COLORTERM:-}" ]] && exec_env_args+=(-e "COLORTERM=${COLORTERM}")
+                [[ -n "${DCLAUDE_ITERM2:-}" ]] && exec_env_args+=(-e "DCLAUDE_ITERM2=${DCLAUDE_ITERM2}")
 
                 debug "Creating new tmux session running Claude"
                 debug "Claude args count: ${#claude_args[@]}, user args: $*"
@@ -1319,6 +1320,11 @@ main() {
         DOCKER_ARGS+=(-e "COLORTERM=${COLORTERM}")
     fi
 
+    # Pass through iTerm2 integration opt-out if set
+    if [[ -n "${DCLAUDE_ITERM2:-}" ]]; then
+        DOCKER_ARGS+=(-e "DCLAUDE_ITERM2=${DCLAUDE_ITERM2}")
+    fi
+
     # Mount Docker socket if detected (detection done earlier for system context)
     if [[ -n "$DOCKER_SOCKET" ]] && [[ -S "$DOCKER_SOCKET" ]]; then
         DOCKER_ARGS+=(-v "${DOCKER_SOCKET}:/var/run/docker.sock")
@@ -1389,6 +1395,7 @@ main() {
             [[ -n "${TERM_PROGRAM_VERSION:-}" ]] && exec_env_args+=(-e "TERM_PROGRAM_VERSION=${TERM_PROGRAM_VERSION}")
             [[ -n "${TERM_SESSION_ID:-}" ]] && exec_env_args+=(-e "TERM_SESSION_ID=${TERM_SESSION_ID}")
             [[ -n "${COLORTERM:-}" ]] && exec_env_args+=(-e "COLORTERM=${COLORTERM}")
+            [[ -n "${DCLAUDE_ITERM2:-}" ]] && exec_env_args+=(-e "DCLAUDE_ITERM2=${DCLAUDE_ITERM2}")
 
             debug "Creating new tmux session running Claude"
             debug "Claude args count: ${#claude_args[@]}, user args: $*"
@@ -1537,6 +1544,7 @@ cmd_attach() {
     [[ -n "${TERM_PROGRAM_VERSION:-}" ]] && exec_env_args+=(-e "TERM_PROGRAM_VERSION=${TERM_PROGRAM_VERSION}")
     [[ -n "${TERM_SESSION_ID:-}" ]] && exec_env_args+=(-e "TERM_SESSION_ID=${TERM_SESSION_ID}")
     [[ -n "${COLORTERM:-}" ]] && exec_env_args+=(-e "COLORTERM=${COLORTERM}")
+    [[ -n "${DCLAUDE_ITERM2:-}" ]] && exec_env_args+=(-e "DCLAUDE_ITERM2=${DCLAUDE_ITERM2}")
 
     # Attach to existing session
     info "Attaching to session: $session_name"

docker/Dockerfile

@@ -114,9 +114,11 @@ USER claude
 WORKDIR /home/claude
 
 # Configure npm to use user directory for global packages
+# Source iTerm2 shell integration if not disabled (only activates in iTerm2)
 RUN npm config set prefix /home/claude/.npm-global \
     && echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.bashrc \
     && echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.bashrc \
+    && echo '[[ "${DCLAUDE_ITERM2:-true}" != "false" && -f ~/.iterm2_shell_integration.bash ]] && source ~/.iterm2_shell_integration.bash' >> ~/.bashrc \
     && echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.profile \
     && echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
 
@@ -148,9 +150,10 @@ USER root
 # Declare volumes for persistent data
 VOLUME ["/home/claude/.claude"]
 
-# Copy entrypoint script and tmux config (paths mirror image structure)
+# Copy entrypoint script, tmux config, and shell integrations (paths mirror image structure)
 COPY --chown=claude:claude usr/local/bin/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 COPY --chown=claude:claude home/claude/.tmux.conf /home/claude/.tmux.conf
+COPY --chown=claude:claude home/claude/.iterm2_shell_integration.bash /home/claude/.iterm2_shell_integration.bash
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 # Set working directory to workspace
@@ -170,7 +173,8 @@ ENV CLAUDE_UNSAFE_TRUST_WORKSPACE=true \
     LANG=en_US.UTF-8 \
     LC_ALL=en_US.UTF-8 \
     LANGUAGE=en_US:en \
-    GIT_CONFIG_GLOBAL=/home/claude/.claude/.gitconfig
+    GIT_CONFIG_GLOBAL=/home/claude/.claude/.gitconfig \
+    ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=1
 
 # Labels
 LABEL maintainer="alanbem" \