Repository navigation
Description
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
- Hosts are already a direction. ACP ([Feature request] ACP Support #319), headless/print mode (Feature request: headless/print mode + SDK support for freebuff authToken (for third-party orchestrators) #947) and the
local TUI inbox (Let another local process hand a prompt to a running Freebuff TUI #1579) each need a host to write a Freebuff integration. OSC 7501
needs none: it is the one channel every terminal already consumes, so Freebuff gets
pane-level presence in tools that will never ship a Freebuff adapter. - It answers "which pane needs me". The free tier runs long sessions, so the user
is usually elsewhere.blockedwithkind=permission|question|authis exactly the
signal a pane list or tab bar routes attention on — the thing hooks cannot see,
because no hook fires while the CLI waits for approval. - It stops being the wrapper's job. Screen-scraping wrappers exist precisely for
agents without this; native reports replace guessing with ground truth.
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/ttywriter and the tmux/screen wrapping above. The state is
already computed bygetStatusIndicatorState,isAskUserActiveand 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
jond34 commentedon Nov 17, 2026
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.jond34 commentedon Nov 17, 2026
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.0on 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-statusThe 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:desktopalongsidearea:cliwould put it in front of the reader who decides that.