Skip to content

feat(windows): add direct Windows Terminal support #4

Description

@MarsSall

Problem

gentle-agent-state supports tmux, Zellij, and native Ghostty, but direct Windows Terminal sessions are not currently routed to a backend.

This means agents running directly in Windows Terminal, including Pi and OpenCode, cannot reliably show agent state in the tab title or play attention/completion notifications.

A local Windows Terminal adaptation has been tested with both Pi and OpenCode. It uncovered one important Windows-specific issue: spawning bash from a direct Windows Terminal session can resolve to the WSL shim. When WSL has no distro installed, the diagnostic output can be printed into the agent TUI and corrupt the input area.

Proposed solution

Add direct Windows Terminal support using WT_SESSION when no multiplexer is active:

  • Detect direct Windows Terminal sessions with WT_SESSION when TMUX_PANE, ZELLIJ_PANE_ID, and ZELLIJ are absent.
  • Add a current-terminal / Windows Terminal backend that updates tab/window title through OSC title sequences.
  • Preserve state transitions: working, idle, blocked, unknown.
  • Preserve notification behavior for blocked and finished transitions.
  • Avoid spawning bash from the Pi direct Windows Terminal adapter path to prevent WSL shim output from corrupting the TUI.
  • Keep tmux, Zellij, and Ghostty behavior unchanged.
  • Use readable tab titles such as <name> working, <name> idle, and <name> blocked for direct Windows Terminal sessions.

Affected area

  • scripts/agent-report.sh
  • new Windows/current-terminal backend script
  • adapters/pi/gentle-agent-state.ts
  • adapters/opencode/gentle-agent-state.js
  • installer/uninstaller
  • README and contract tests

Acceptance criteria

  • Direct Windows Terminal sessions are detected via WT_SESSION.
  • Direct Windows Terminal sessions update the tab/window title for working, idle, and blocked.
  • Direct Windows Terminal sessions preserve blocked/finished notification sounds or a safe fallback.
  • Pi direct Windows Terminal reporting does not spawn bash for state updates.
  • tmux, Zellij, and Ghostty behavior remains unchanged.
  • OpenCode and Pi adapters both route Windows Terminal state correctly.
  • Contract tests cover Windows Terminal dispatch/title behavior.

Duplicate check

I searched existing issues for Windows Terminal, WT_SESSION, opencode terminal, and ghostty windows and did not find a duplicate.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions