Background task logs should be streamable via clickable link or auto-opened terminal

Problem

When Claude Code runs background tasks (via run_in_background in Bash tool or background Agents), the user has zero visibility into what's happening until the task completes. There are no logs, no progress, no way to watch — just "I'll notify you when done."

This is a black box experience. For long-running tasks (builds, test suites, deployments, large file operations), the user has no idea if it's stuck, failing, or progressing normally.

Proposed Feature: Streamable Background Task Logs

Core idea

When a background task starts, Claude Code should:

1. Pipe all task output to a known temp file (e.g., /tmp/claude-code-bg-<task-id>.log)
2. Display a clickable terminal hyperlink (OSC 8) that the user can click to view live logs
3. Optionally auto-open a terminal pane showing live logs

User-facing experience

⏳ Background task started: running test suite
   📋 Logs: /tmp/claude-code-bg-a1b2c3.log  [Click to open]
   💡 Tip: Press Ctrl+Shift+L to open log viewer

Terminal integration strategies

With tmux / screen (auto-detected)

• If Claude Code detects it's running inside tmux, auto-open a split pane: tmux split-window -h "tail -f /path/to/log"
• Each bg task gets its own pane — user can navigate with standard tmux shortcuts
• Pane auto-closes when task completes (configurable)

With Kitty / WezTerm (terminal API)

• These terminals expose APIs to programmatically open new tabs or windows
• Claude Code could open a new tab with the log stream — no user setup required

With GNOME Terminal / Windows Terminal / iTerm2 (OSC 8)

• Display a clickable OSC 8 hyperlink pointing to the log file
• Format: \e]8;;file:///tmp/claude-bg-a1b2c3.log\e\\Click to view logs\e]8;;\e\\
• User clicks → file opens in default handler or terminal viewer

Plain terminal (fallback)

• Always print the log file path so the user can tail -f it manually in another terminal
• This is the minimum viable experience — no setup needed

Configuration flags

{
  "backgroundTasks": {
    "logToFile": true,
    "logDir": "/tmp/claude-code-logs",
    "autoOpenTerminal": false,
    "autoOpenTerminal.mode": "split"
  }
}

• logToFile (default: true) — write bg task output to a log file
• logDir (default: system temp dir) — where to store log files
• autoOpenTerminal (default: false) — automatically open a new terminal pane showing live logs when a bg task starts
• autoOpenTerminal.mode:
• "split" — tmux/screen split pane
• "tab" — new terminal tab (Kitty/WezTerm API)
• "window" — new terminal window

Summary

| Terminal environment | Auto-open method | Fallback |
|---|---|---|
| tmux / screen | tmux split-window (auto-detected) | Log file path printed |
| Kitty / WezTerm | Terminal API new tab | OSC 8 clickable link |
| GNOME Terminal / iTerm2 / Windows Terminal | OSC 8 clickable link | Log file path printed |
| Plain / unknown terminal | Log file path printed | tail -f manually |

Additional improvements

• Log rotation / cleanup — auto-delete log files after task completes (configurable retention)
• Multiple bg tasks — show a task list with all running bg tasks and their log file paths
• Progress indicators — parse common patterns (percentage, step counts) from logs and show a progress bar inline

Current workarounds (all unsatisfying)

1. Add instructions in CLAUDE.md to manually tee output to a file — fragile, not universal
2. Run Claude Code inside tmux and manually tail files — requires user setup
3. Don't use background tasks — defeats the purpose of parallel execution

Why this matters

Background tasks are one of Claude Code's most powerful features — running tests while continuing to code, building in parallel, etc. But without log visibility, users either:

• Avoid background tasks entirely (losing parallelism)
• Wait anxiously with no feedback
• Get surprised by failures they could have caught early

Making background task logs accessible and optionally auto-viewable in the terminal would significantly improve the CLI developer experience.

Environment

• Affects: Claude Code CLI (terminal)
• Category: Developer experience, Background tasks, Terminal UI