Official integrations never report pane titles — task-based renaming is missing and crucial

[RaviTharuma]

Originally filed as #1723 and closed because Herdr routes feature requests to Discussions. Reposting here as an Ideas discussion.

Summary

Pane renaming / task-title metadata is missing from Herdr's official integrations, and that gap is crucial.

Herdr already has the right primitives:

• herdr pane report-metadata --title ... --display-agent ...
• herdr pane rename
• herdr agent rename

But the shipped integrations (Pi, OMP, Claude Code, Codex, OpenCode, Cursor, Factory, etc.) only call:

• pane.report_agent_session
• pane.report_agent
• pane.release_agent

They never call pane.report_metadata with a useful --title / --display-agent derived from the user's task.

Result: a herd of panes all labeled pi, claude, codex, opencode — useless when you have 5–15 agents running.

Why this is crucial

Herdr's value proposition is seeing the whole herd at a glance. Without task-derived pane titles:

1. Sidebar/agent panel is unreadable — every row is the same agent binary name.
2. Focus / attach / wait workflows degrade — herdr agent focus requires guessing which pane is which.
3. Outer terminal titles stay empty — plugins like rjyo/herdr-window-title-sync explicitly prefer Herdr pane metadata title first, then fall back to scraping session files. When integrations don't report titles, the ecosystem has to reverse-engineer prompts from disk.
4. Third-party renamers proliferate (herdr-auto-namer, herdr-plugin-renamer, terminal-title hooks per agent) because the core loop doesn't do the obvious thing.
5. Multi-agent orchestration is slower — humans and automations both waste time mapping "which pane is the auth refactor?"

This is not a nice-to-have cosmetic. Task identity is the primary UX surface of an agent multiplexer.

Current state (reproduced on herdr 0.7.5)

Installed official integrations checked — none report metadata titles:

Integration path	report_metadata / title?
~/.pi/agent/extensions/herdr-agent-state.ts	no
~/.omp/agent/extensions/herdr-omp-agent-state.ts	no
~/.claude/hooks/herdr-agent-state.sh	no
~/.codex/herdr-agent-state.sh	no
~/.config/opencode/plugins/herdr-agent-state.js	no

Docs already show the intended pattern (website/src/content/docs/integrations.mdx):

herdr pane report-metadata "$HERDR_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --ttl-ms 3600000

…but that is left as a user hook exercise instead of being built into the integrations that already observe prompts/sessions.

Proposed fix (core + integrations)

1. Official integrations should report titles by default

On first user prompt (and on meaningful task changes), each integration should:

pane.report_metadata
  source: herdr:<agent>   # or integration-owned source id
  title: <short task title>
  display_agent: <Agent: short-title>   # optional
  ttl_ms: reasonable default / refresh on activity

Sources of title, in priority order:

1. Agent-native session title if the product already has one (Claude Code session title, Codex thread title, etc.)
2. First user prompt, compressed to ~40–60 chars
3. Explicit rename if user/agent set one
4. Fallback: cwd basename / branch — better than bare claude

2. Keep lifecycle and presentation separated (already designed)

Continue using report_agent for idle/working/blocked only.
Use report_metadata for title/display-agent/state-label.
This matches the existing architecture from #36 / 0.6.3.

3. Optional: auto-title helper in Herdr core

A small shared helper used by all integrations:

• summarize_title(prompt) -> string (local heuristic first; optional model later)
• debounced updates (don't rename on every keystroke / every tool call)
• clear/restore policy on new session, fork, session end

4. Document as a first-class integration requirement

In integration authoring docs, mark task title reporting as required, not optional:

An integration is incomplete if it reports agent state but not a human-readable pane title.

Acceptance criteria

• Pi / OMP / Claude / Codex / OpenCode official integrations report a non-empty pane title after the first user prompt
• Agent panel shows distinct labels for concurrent same-type agents
• herdr-window-title-sync can prefer integration-reported metadata without scraping JSONL
• Titles update on new session / clear on release without fighting user renames
• Docs list title reporting next to state reporting as required behavior

Related ecosystem pressure (symptoms of this gap)

• https://github.com/rjyo/herdr-window-title-sync — outer title sync; wants pane metadata title first
• https://github.com/kakigakki/herdr-auto-namer — Claude session title to agent name
• https://github.com/wyattjoh/herdr-plugin-renamer — LLM rename from first prompt
• https://github.com/bluzername/claude-code-terminal-title — OSC titles outside Herdr
• https://github.com/zhzy0077/opencode-terminal-title — OpenCode terminal titles

These exist because pane renaming is missing from the default loop. Closing this in core integrations would collapse a lot of fragile per-agent glue.

Environment

• herdr 0.7.5 (Homebrew)
• macOS
• integrations installed via herdr integration install …

Thanks — happy to test a PR against Pi + Claude integrations first.

[RaviTharuma]

Implementation path (ready for review / maintainer direction)

Negotiated split so title/rename work does not fork into conflicting PRs:

Primary (this discussion)

Official integrations report short task titles via existing pane.report_metadata after the first user prompt, and clear on new/resume.

• Branch (fork): https://github.com/RaviTharuma/herdr/tree/feat/integration-task-titles
• Commit: ee29ae8 — feat(integration): report task titles from first user prompt
• Touches: Pi, Oh My Pi, Claude, Codex, OpenCode, Kilo integration assets + tests + changelog
• Checks: bun test src/integration/assets/herdr-agent-state.test.ts (16 pass) and opencode unit tests (2 pass)

Explicitly out of scope for this branch

• Plugin context-menu / pane-mover right-click wiring stays a separate change and must not reimplement title reporting.
• Third-party renamers / window-title-sync remain complementary consumers of metadata titles.

Happy to open a PR once a maintainer accepts this idea (or converts this discussion to an issue) per CONTRIBUTING.

[RaviTharuma]

Related reproducible bugs found while re-checking this idea

Leaving this Ideas discussion open for the product ask (official integrations should report task titles). Separately, the metadata CLI currently has real bugs that block reliable title reporting from hooks/integrations:

1. pane report-metadata help form fails; only pane-id-first form works #1771 — pane report-metadata help/usage form fails; only pane-id-first works
2. pane report-metadata partial updates clear other metadata fields #1772 — partial metadata updates clear other fields (title wiped by later display-agent/state-label)

These are filed as template-compliant bug reports. The original feature request remains here in Discussions.

[RaviTharuma]

Opened as issue for tracking: #1775

Related reproducible metadata CLI bugs:

• pane report-metadata help form fails; only pane-id-first form works #1771
• pane report-metadata partial updates clear other metadata fields #1772

[badlogic]

Hey, Mario here, creator of pi. I was just trying out herdr today and fixed up the herdr pi extension to report metadata correctly:

https://gist.github.com/badlogic/d201ca89b3af03d974961f64607739f6

Happy to send a PR!

[RaviTharuma]

@badlogic Hallo Mario! Nice to meet you

[ogulcancelik]

hey @badlogic, nice to see you here ! (i thought armin was the creator as people say)

added you to contributor list, though on this issue i'm not sure if each extension should by default change presentation state. people many not want to auto rename tabs, or may have multiple agent panes in a tab. some might prefer auto naming pane borders.

so i think better option is that each integration reports/populates agent-session metadata so that everyone can write a simple plugin to do any representation automation they want; auto rename tabs or pane borders or sidebar statuses.

i'm planning to open pane.agent_session_changed events to plugin api.

[badlogic]

sounds good to me! i'm but a herdr baby user, so i don't know the ropes yet. easy enough to keep using my vibe slopped mod until you folks make a good version that afheres to herdr principles.

[yuval-shimoni-cyera]

For what it's worth, here's how I've been solving this on my side while the core integration catches up.
I wrote a small Herdr extension for Pi with few convenience slash commands:

/herdr-new-tab [label], /herdr-name-tab [label], /herdr-close-tab — that wrap herdr tab <..> from inside Pi, so I don't reach for the Ctrl+B prefix for common tab ops.

/herdr-name-tab with no arg falls back to the current Pi session name.

This doesn't solve the core problem in the OP — it's not reporting metadata or auto-titling. But it makes Pi inside Herdr noticeably smoother: I can spin up, name, and close tabs straight from Pi slash command, without breaking flow to hit Ctrl+B and remember the right shortcut.

herdr-pi-demo.mp4

[serenNan]

A narrower path that needs no integration changes

Complementary to the integration-reported metadata ask above, not a replacement: there is a subset of this problem Herdr can already solve on its own, because the data is already in the runtime and simply unused by the tab bar.

The data already arrives

Claude Code (and several other agents) broadcast their session name over OSC 0/2. Herdr already captures this: AgentOscTracker in src/pane/osc.rs tracks both the raw and the stripped title (stripped drops the spinner prefix, so it only changes on a real title change), and TerminalState stores it. The sidebar's terminal_title_stripped token consumes it today.

So when a user runs /rename inside Claude Code, Herdr receives the new name. It just never reaches the tab bar.

The gap

Workspace::tab_display_name() resolves in two steps only:

tab.custom_name.clone().unwrap_or_else(|| (tab_idx + 1).to_string())

No terminal-title term. A tab running an agent with a meaningful session name still renders as 1.

What a third resolution step looks like

custom_name → stripped terminal title → ordinal, with these constraints:

• Agent panes only. Requires detected_agent.is_some(). Shell panes broadcast cwd and running command names, which carry no session meaning.
• Active pane only. Non-focused panes in a split do not name the tab.
• Presentation only. The derived name is not persisted to snapshots and is not reported as the API label — tab.list / TabInfo.label / tab.renamed keep describing explicit labels only. Reusing tab_display_name() for the API leaks it, so the API path needs its own accessor.
• Still an automatic name. is_auto_named() stays keyed on custom_name, so tab-bar styling and the rename modal's keep_auto_name path are unaffected.
• Configurable, defaulting to enabled.
• Bounded width. Session titles run long, so the tab bar needs a max width with display-width-aware truncation, otherwise one long name pushes sibling tabs off the bar.

Repaint is the one non-obvious piece: the existing full-render trigger for title changes is gated on a sidebar token being configured, so it has to widen to "a derived tab name actually changed" or the tab bar goes stale until unrelated input arrives.

Why this is worth separating from the integration ask

#1775 was closed not planned, and the cost argument there is legible: reporting task titles means touching every official integration and keeping them in sync. This path touches none of them. It is one resolution step plus a repaint condition, entirely inside Herdr, and it works today for any agent that already sets a terminal title.

It does not cover what #1725 asks for. Pane-level metadata titles, non-focused panes, and agents that set no terminal title all remain unsolved, and a first-prompt-derived title is strictly better than a session name. But it turns the most common case — one agent per tab, user renames the session — into something that works without ecosystem coordination.

I have this implemented and running locally against 0.7.5 (config flag, agent/focus gating, API and persistence boundary, width clamp, repaint trigger, tests). Happy to open a PR if this direction is wanted; equally happy to leave it if the tab bar is deliberately explicit-rename-only.