[FEATURE]: add tui.footer.items plugin hook for persistent status display

Currently the only TUI-facing plugin hook for displaying information is tui.toast.show, which creates ephemeral notifications. Several plugins (token-tracker, tps-meter) use toasts to show persistent status, which creates a stream of popups that's disruptive during focused work.

I'd like to propose a tui.footer.items hook that lets plugins inject persistent status items into the session footer:

"tui.footer.items"?: (input: {
  sessionID: string;
}, output: {
  items: Array<{
    key: string;        // unique identifier for dedup
    text: string;       // display text
    fg?: string;        // foreground color (theme token or hex)
    priority?: number;  // ordering hint (lower = further left)
  }>;
}) => Promise<void>;

The footer component would call this hook on each render cycle (or on a timer) and merge plugin items with the built-in items (LSP, MCP, permissions). Plugin items would appear between the directory path and the built-in status items.

This would let the token-tracker plugin show $0.42 · 4.5M tok persistently in the footer instead of firing toasts. It would also enable other plugins to surface persistent status (build status, test results, deployment state) without notification spam.

I understand this is an API surface change and would want maintainer input on the design before implementing. Happy to iterate on the hook shape.

Thanks for updating the issue! It now meets our contributing guidelines. The title, description, and proposed API design all look good.

Strong +1 from the plugin side. We have an OpenCode plugin (opencode-aidevops) that currently uses toasts and system prompt injection for status — a footer hook would be a much better fit for persistent info like framework version, active agent, and cost tracking. Happy to be an early adopter and provide feedback on the API shape.

@marcusquinn

Thanks @marcusquinn -- that's exactly the use case.

For context, #13885 by @diegomarino proposes a template-based status line system where plugins provide data via {plugin:key} template variables. That's a config-driven approach (user writes template strings). This issue (#18969) proposes a code-driven approach (plugin pushes structured items with text, color, priority).

They're complementary rather than competing:

Template system (feat(tui): add native status line template system #13885): user controls layout and formatting via config
Footer hook ([FEATURE]: add tui.footer.items plugin hook for persistent status display #18969): plugin controls what data is available programmatically

If #13885 lands with plugin data support, this hook might not be needed separately. But if the template system doesn't include plugin data, a simpler tui.footer.items hook would fill the gap.

Happy to defer to whichever approach the core team prefers.

+1 was about to make an issue for a persistent runtime timer, this would make this possible without locking into a UI change

Using OpenCode alongside Claude Code, Codex, and Pi in a Nix-managed multi-agent setup. We can align Claude via its scriptable status line, Codex via native items, and Pi via a managed footer extension, but OpenCode is still the outlier because we cannot find a stable persistent footer/status plugin surface in the documented config/plugin APIs.

A hook like or a plugin-rendered status/footer slot would let us project the same structured status facets across tools without scraping terminal output or forking the TUI. The concrete facets we want to align are things like model, cwd/project, git branch, context usage, cost/usage, session/thread identity, and approval/sandbox state.

For local tracking we added TODOs against this blocker while implementing the other clients. Related issue: #8619.

Using OpenCode alongside Claude Code, Codex, and Pi in a Nix-managed multi-agent setup. We can align Claude via its scriptable status line, Codex via native /statusline items, and Pi via a managed footer extension, but OpenCode is still the outlier because we cannot find a stable persistent footer/status plugin surface in the documented config/plugin APIs.

A hook like tui.footer.items or a plugin-rendered status/footer slot would let us project the same structured status facets across tools without scraping terminal output or forking the TUI. The concrete facets we want to align are things like model, cwd/project, git branch, context usage, cost/usage, session/thread identity, and approval/sandbox state.

For local tracking we added TODOs against this blocker while implementing the other clients. Related issue: #8619.

We hit this exact gap while building background and delegated agent workflows in OpenCode plugins. The missing piece is not just generic status text, but a low-noise persistent surface where a plugin can show runtime state like active jobs, queued jobs, or sync progress without falling back to toasts, logs, or transcript injection.

In our case, something as small as "BG: 2 running" or "Delegates: idle" in the footer would already solve the usability problem. A structured plugin hook like tui.footer.items feels like the smallest useful surface because it keeps the data UI-only, avoids token and context pollution, and does not force plugins to fake a status line with notifications.

If the template-based status line work from #13885 ends up exposing plugin-provided data cleanly, that could also cover this use case. If not, this hook still seems like the most direct plugin-facing API for it.

Adding one more concrete plugin use case here from the background-agent/delegation side.

We are building OpenCode plugin workflows where a primary agent can delegate work to background agents while continuing the main conversation. The missing UX surface is a low-noise, persistent footer/status item showing whether background agents are active, for example:

BG: idle
BG: 2 running
BG: sdd-verify +1

Toasts are useful for completion events, but they are not a good fit for ongoing runtime state. Transcript/system-prompt injection is also the wrong layer because this is UI-only state and should not affect model context.

A hook like tui.footer.items would be enough for this use case: the plugin owns the runtime state, OpenCode owns placement/truncation/rendering. If #13885 lands with plugin-provided status line variables and a session_footer target, that could also solve this cleanly.

Looks like the author of #13885 closed it unmerged & without comment.

The workarounds I implemented in aidevops was to append information to the session title: marcusquinn/aidevops#25227

Great proposal — this hook is exactly what's needed for third-party provider quota display in the footer. Concrete use case: a Z.AI GLM coding-plan provider exposes a usage/quota API, and I'd like to render 5h: ███░░░░░ 34% (reset at 18:40) persistently (a plugin polling the endpoint every ~60s and returning one item). Toasts can't represent a progress bar meaningfully, so the persistent footer item is the right surface. The priority ordering hint and theme-token fg would also let plugins color the bar by remaining quota (green/yellow/red). +1.

+1 from practical usage.

I'm on the OpenCode Go subscription and wanted session usage limits (5h / weekly / monthly) in the session footer. The V2 TUI slot API made this possible today — a CLI plugin renders the quota percentages + reset countdowns on prompt.footer, using GET /zen/go/v1/usage.

Two gaps remain that this hook (or a related config toggle) would close:

Hiding builtin footer elements. The command hints (ctrl+p commands) and the $ cost label are hardcoded in the builtin opencode.prompt.footer plugin — there's no config to hide them. The V1-era requests ([FEATURE]: Add hints toggle to declutter UI #6240, [FEATURE]: Hide redundant prompt footer context when sidebar is visible #20145) were closed as stale and their code paths no longer exist in V2. Dollar cost is redundant once quota is shown as percentages, and the hints are noise once you know the shortcuts.
Replace semantics. The slot replace placement removes everything on the path (builtin children + other plugins' appends), so a plugin can't suppress a single builtin element without reimplementing the whole footer.

Suggestion: the footer items hook proposed here, plus opt-out config for builtin footer segments (cost, hints), would cover both. Happy to test any prototype against the Go usage plugin.

TUI plugins in OpenCode v2 can show persistent status in footer slots: prompt.footer, prompt.footer.status, home.footer and home.footer.status. This replaces using toasts to show ongoing status.

Added in #41189; home.footer.status came in #48798.

Closing as completed. If something doesn't work on v2, please open a new issue.

Navigation Menu

Repository navigation

[FEATURE]: add tui.footer.items plugin hook for persistent status display #18969

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE]: add tui.footer.items plugin hook for persistent status display #18969

Description

Activity

github-actions commented on Mar 24, 2026

marcusquinn commented on Mar 25, 2026

andrewdunndev commented on Mar 25, 2026

christian-berard-fhr commented on Apr 1, 2026

schickling-assistant commented on Apr 17, 2026

schickling-assistant commented on Apr 17, 2026

Alan-TheGentleman commented on Apr 22, 2026

IrrealV commented on Apr 23, 2026

zcutlip commented on Jun 23, 2026

marcusquinn commented on Jun 23, 2026

phalla-doll commented on Jul 17, 2026

lnwu commented on Sep 4, 2026

neriousy commented on Oct 1, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions