Skip to content

Report agent status via OSC 7501 (Program Status Protocol) #1676

Open

Description

@jond34

What problem are you trying to solve?

Freebuff sets its terminal title but never reports program status, so terminals and
multiplexers that build an agent list from the Program Status Protocol (OSC 7501) show
a Freebuff pane as a plain shell. Herdr's app runtime is one of them: it draws only from
program-emitted status — "herdr-core draws nothing and guesses nothing… No screen
scraping, no list of known agents" (https://herdr.dev/core). The only workaround today
is a terminal-side wrapper, which neither project wants to own.

This has been asked and answered for other CLIs already: herdrdev/herdr#5700 (Devin),
herdrdev/herdr-app#125 (Copilot — "that has to come from copilot, so it's worth asking
them for 7501 support"), github/copilot-cli#5320.

Where Freebuff sits today

Every mainstream agent CLI reports it, and Zellij maintains the list
(https://zellij.dev/documentation/inbox-integrations.html):

Agent First reporting version
Claude Code 2.1.295
Codex CLI 0.163.0
OpenCode 2.1.0
Crush 0.98.0
GitHub Copilot CLI 1.0.106
Qwen Code 0.26.9
goose 1.56.0
Factory Droid CLI 0.236.0
Kimi Code, Kiro CLI, Amp, Antigravity current releases
Pi 1.1.0

Gemini CLI is the notable holdout, with an open request
(google-gemini/gemini-cli#29710). So in Herdr, Zellij, TUIOS, Termio or Vibe42,
Freebuff is the one agent in the group that still looks like a shell.

Why it matters for Freebuff specifically

Proposed solution

One report per state transition, written to the controlling tty:

\x1b]7501;state=working:app=freebuff\x1b\\

state is required (idle | working | blocked | done | error | clear); kind only
with blocked; msg and title are base64 single-line text; app=freebuff so a
terminal can group and label the record. The map from state Freebuff already tracks
(cli/src/utils/status-indicator-state.ts) is direct:

Freebuff event report
prompt submitted, streaming, waiting, connecting, retrying, capacityWait state=working:app=freebuff
ask_user active state=blocked:kind=question:app=freebuff
auth unreachable / login needed state=blocked:kind=auth:app=freebuff
turn finished, result not yet seen state=done:app=freebuff
prompt focused, nothing running state=idle:app=freebuff
turn failed state=error:app=freebuff
Ctrl+C / cancel state=idle:app=freebuff

kind=permission has no source today: the CLI has no tool-approval prompt, so the only
candidate is the .agents/MCP trust gate. progress, title and msg are not needed
for pane-level presence, and are follow-ups rather than part of a first cut.

Two details that cost time if missed: the sequence has to reach /dev/tty, not stdout,
or OpenTUI's capture eats it; and inside tmux it needs the same DCS passthrough the
title code already applies. Both are already written for the title — setTerminalTitle
goes through writeTerminalControlSync (cli/src/utils/terminal-io.ts) for exactly
this reason, and buildTitleSequence does the wrapping — so a report is the same bytes
with ]7501; instead of ]0;. Feature detection is optional in revision 0.4 (a
program MAY report without answering the OSC 7501;? probe), so nothing has to change
on the terminal side, and a terminal that ignores 7501 sees no difference.

Scope

  • Files: new cli/src/utils/program-status.ts (sequence builder and the
    indicator-to-report map); call it where the title and status indicator are already
    computed. No new setting: a terminal that does not implement 7501 ignores it, so an
    off switch can wait until someone wants one.
  • Reuses: the /dev/tty writer and the tmux/screen wrapping above. The state is
    already computed by getStatusIndicatorState, isAskUserActive and the auth status,
    so no new tracking.
  • Lines: ~80, plus unit tests for the encoder (wrapping, truncation, sanitizing).
  • New dependencies: none.
  • Breaking changes: none. Observational only — permissions, auth and the ad path are
    untouched.

Happy to help

I maintain a Herdr TUI plugin for Freebuff (https://github.com/jond34/herdr-freebuff)
that reports state through Herdr's socket API today; with native 7501 that layer would
go away. I can test a build against herdr-app, herdr-core, Zellij and tmux and report
back what each renders.

Area

CLI (terminal client)

Activity

  1. jond34 commented on Nov 17, 2026

    @jond34
    Author

    Opened #1677 with an implementation of this. It builds the report from the status indicator the CLI already derives and emits on change; unit tests cover the exact bytes and the tmux wrapper, and the built binary emits \x1b]7501;state=idle:app=freebuff\x1b\\\\ in a plain pty and the same report inside a tmux DCS wrapper.

  2. added
    area:cliThe Codebuff/Freebuff terminal client
    bot:triagedClassified by the community triage bot
    type:featureA request for new behavior
    on Nov 17, 2026
  3. jond34 commented on Nov 17, 2026

    @jond34
    Author

    Desktop keeps up to 12 sessions alive and the user is looking at one of them. The rest run in a tab behind another app, a tmux pane, a Herdr or Zellij workspace, a cloud sandbox, or on someone's SSH box. None of those apps can read Freebuff's internals, so the user finds out that a turn finished or a permission prompt is waiting by going back and looking. A session waiting on a prompt produces nothing until someone looks.

    A status report on the pty reaches all of them. Freebuff already owns the pty, whatever app surrounds it already reads that stream, and terminals that don't know the sequence ignore it. No per-surface integration, no socket, no screen scraping.

    The sequence isn't Herdr's and nothing reserves it. Claude Code 2.1.295 emits it (2026-10-08, https://github.com/anthropics/claude-code/blob/v2.1.295/CHANGELOG.md), Codex since 2026-10-09 (shipped in rust-v0.163.0 on 2026-10-15, openai/codex#52725), Crush since 0.98.0 (2026-10-08, https://github.com/charmbracelet/crush/releases/tag/v0.98.0). iTerm2 3.7.5 reads it (2026-10-14, https://iterm2.com/downloads/stable/iTerm2-3_7_5.changelog), kitty since 0.50.0 (2026-11-03, kovidgoyal/kitty#10638), Zellij since 0.46.0 (2026-11-11, https://zellij.dev/news/terminal-inbox-session-previews/), libghostty since 2026-10-06 (ghostty-org/ghostty#14560). Spec, rev 0.4 on 2026-10-10: https://www.superlogical.com/rex/docs/build/program-status

    The implementation is on #1663 and still in review. This issue asks for the other half: the status is a Desktop surface problem, not a CLI detail, and it belongs below the app rather than inside each app's integrations. area:desktop alongside area:cli would put it in front of the reader who decides that.

  4. added
    area:desktopThe Electron desktop app
    and removed
    area:cliThe Codebuff/Freebuff terminal client
    on Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:desktopThe Electron desktop appbot:triagedClassified by the community triage bottype:featureA request for new behavior

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions