Native split-pane mode for CLI

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Request

Native split-window/pane mode for working on larger screens.

Use Case

When running long tasks (overnight tests, complex implementations), I want to:

• See task/instructions on one side
• Watch execution/output on the other
• Monitor without scrolling through interleaved output

Current Workaround

Using tmux or iTerm2 split panes, but loses Claude Code's native UI benefits.

Proposed UX

┌─────────────────────┬───────────────────┐
│ Context/Instructions│ Execution/Output  │
│                     │                   │
│ Task details        │ > Working...      │
│ Watched files       │ > Tests passing   │
│ Chat history        │ > Committing...   │
└─────────────────────┴───────────────────┘

Could be triggered with claude --split or a keybinding.

Environment

• macOS / Large external monitor
• Heavy CLI user

Proposed Solution

Activation

• CLI flag: claude --split
• Runtime toggle: keyboard shortcut (e.g., Ctrl+\) to enable/disable
• Config option: "splitMode": true in ~/.claude.json for default behavior

Layout

┌───────────────────────────┬───────────────────────────┐
│ CONTEXT                   │ EXECUTION                 │
│                           │                           │
│ • Current task/prompt     │ • Live streaming output   │
│ • Files being modified    │ • Tool calls in progress  │
│ • Conversation history    │ • Diffs and edits         │
│   (scrollable)            │ • Test results            │
│ • Token usage             │ • Errors and warnings     │
│                           │                           │
├───────────────────────────┴───────────────────────────┤
│ > Input prompt                                        │
└───────────────────────────────────────────────────────┘

Behavior

• Left pane: Scrollable context — what Claude knows, task description, watched files, chat history
• Right pane: Streaming execution — what Claude is actively doing
• Input: Stays at bottom, spans full width
• Navigation: Tab or Ctrl+←/→ to switch focus between panes
• Resize: Configurable split ratio (50/50, 30/70) via config or drag

Graceful degradation

• Falls back to single-pane on narrow terminals (< 120 columns)
• --no-split flag to override if split mode is set as default

Why this helps

Long-running tasks (multi-file edits, tests, overnight runs) currently require external tools like tmux to monitor progress while reviewing context. Native split support would keep everything in one interface with Claude's styling and keybindings intact.

Alternative Solutions

Current workarounds

tmux / screen

• Split terminal manually with Ctrl+b % or Ctrl+b "
• Run Claude in one pane, monitor logs/files in another
• Limitation: Loses Claude's native TUI benefits, keybindings can conflict, requires extra setup

iTerm2 / Terminal.app split panes (macOS)

• Cmd+D for vertical split
• Limitation: Panes are independent — no shared context, can't see Claude's internal state in the other pane

VS Code split terminal

• Split integrated terminal, run Claude in one side
• Limitation: Same as above — just two independent terminals

Running with --verbose or --debug flags

• See more output in single pane
• Limitation: Everything interleaved, hard to follow during long tasks

Why these fall short

All workarounds create two separate views rather than a unified interface. There's no way to:

• See Claude's current context (files, memories, task) while watching execution
• Keep Claude's styling and keybindings consistent across both views
• Have the split be context-aware (e.g., left pane automatically shows relevant files)

A native solution would make monitoring long-running agentic tasks significantly easier without leaving Claude's environment.

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

Scenario: Complex multi-file refactoring task

Step 1: Paste detailed instructions

> Refactor the authentication module:
  - Extract JWT logic into separate service
  - Update all 12 files that import auth
  - Add unit tests for new service
  - Update API documentation

Step 2: Work in split view

• Left pane: My original instructions stay visible, plus the list of files Claude is tracking
• Right pane: Live execution — file edits streaming, test runs, progress

Step 3: Reference instructions while reviewing changes
Claude is editing file 7 of 12. I glance at the left pane to confirm "yes, JWT extraction was part of the ask" without interrupting the flow or pressing Ctrl+O to toggle views.

Step 4: Catch issues mid-task
I spot Claude heading in the wrong direction on file 9. I can see both my original intent (left) and what's happening (right) simultaneously — no toggling, no guessing.

---

Why this helps

Current workflow: Instructions disappear as output streams. To review them, I press Ctrl+O to scroll back, losing sight of live execution. It's a constant toggle between "what did I ask for?" and "what's happening now?"

With split mode: Both stay visible. The mental context-switching disappears. Especially valuable for:

• Long multi-step tasks where the original prompt scrolls off-screen
• Reviewing file change diffs while keeping the task description in view
• Monitoring test output without losing sight of what's being tested
• Any agentic workflow where execution takes several minutes

Additional Context

Mockup

┌─────────────────────────────┬─────────────────────────────┐
│ CONTEXT                     │ EXECUTION                   │
│                             │                             │
│ Task:                       │ [3/5] Editing auth.py...    │
│ Refactor auth module into   │                             │
│ separate JWT service...     │ - def verify_token(...)     │
│                             │ + from jwt_service import   │
│ Files:                      │ + def verify_token(...)     │
│ ✓ auth.py                   │                             │
│ → jwt_service.py (editing)  │ Running tests...            │
│ ○ api/routes.py             │ ✓ test_jwt_encode           │
│ ○ api/middleware.py         │ ✓ test_jwt_decode           │
│                             │ ✗ test_token_expiry         │
│ Tokens: 45k/200k            │                             │
├─────────────────────────────┴─────────────────────────────┤
│ > _                                              [Sonnet] │
└───────────────────────────────────────────────────────────┘

Similar features in other tools

| Tool | Implementation |
|------|----------------|
| Vim/Neovim | :vsplit for vertical split, seamless buffer management |
| tmux | Ctrl+b % splits panes, but external to app |
| Zellij | Built-in layouts with named panes |
| LazyGit | Split view showing diff + file list + commit history simultaneously |
| k9s | Multi-pane Kubernetes dashboard in terminal |
| Midnight Commander | Classic dual-pane file manager TUI |

These tools demonstrate that rich split layouts are achievable and ergonomic in terminal UIs.

Technical considerations

• Ink/React-based TUI: Claude Code already uses Ink — libraries like ink-box or flexbox-style layouts could support split rendering
• Minimum terminal width: Degrade gracefully to single-pane below ~120 columns
• State sync: Left pane would need access to internal state (file list, token count, task context) that's already tracked
• Performance: Only re-render changed pane regions to avoid flicker (Ink supports this)
• Accessibility: Ensure screen readers can navigate between panes logically

Related issues

• #6661 — Toad framework migration (mentions responsive layouts)
• #6747 — Request for bottom panel docking in VS Code (similar UX motivation)
• #4851 — Scrollback buffer issues in tmux (workaround that native split would obviate)