A HUD or statusline is a host UI surface. It is not an MCP tool, not a resource, and not something the model calls. The host asks for a short render result, and agent-connector dispatches your statusline.render(ctx) handler where that host supports it.

Why it is separate from MCP#

MCP moves capability messages between a host and a server. A statusline is the host displaying state to a human: current connector, project, token state, warning flags, or another compact signal. It belongs in the host UI layer, not in the MCP server's tool list.

Host UI asks for a statusline render
        |
        v
Adapter calls agent-connector statusline runtime
        |
        v
statusline.render(ctx) returns short text
        |
        v
Host displays it in its native HUD/statusline area

Official host model#

The clearest official model is Claude Code's statusLine command: the host runs a command, passes session metadata on stdin, and displays the command's short stdout. agent-connector uses that command-stdin shape where a host exposes a comparable connector-owned statusline surface.

The render callback#

The connector declares one statusline surface. At runtime, the host adapter asks the home binary to resolve the connector and call render(ctx). The handler should be deterministic, quick, and short enough for the host's native status area.

• Use it for glanceable state, not instructions or long explanations.
• Avoid network calls; status UI may refresh often and should not block the host.
• Return plain text unless a host-specific adapter explicitly supports richer output.

Define a connector statusline#

The handler receives normalized host context. The same handler can read the current host, model, workspace, context usage, and this connector's telemetry rollup where the runtime can provide it.

import { defineConnector, defineStatusline } from "@ken-jo/agent-connector/sdk";

const statusline = defineStatusline({
  description: "Show acme-db connector state.",
  options: {
    refreshInterval: 5,
    maxLines: 2,
  },
  render(ctx) {
    const model = ctx.model?.displayName ?? ctx.model?.id ?? "model";
    const calls = ctx.usage?.calls ?? 0;
    const pct = ctx.context?.percent;
    const context = pct == null ? "" : ` · ctx ${Math.round(pct)}%`;

    return `acme-db · ${model} · ${calls} calls${context}`;
  },
  hosts: {
    "claude-code": {
      render(ctx) {
        return `acme-db · ${ctx.cwd ?? ctx.projectDir ?? "workspace"}`;
      },
    },
    "qwen-code": {
      options: {
        respectUserColors: true,
        hideContextIndicator: true,
      },
    },
  },
});

export default defineConnector({
  server: { transport: "stdio", command: "node", args: ["./my-mcp-server.mjs"] },
  statusline,
});

Rendered host config#

For Claude Code, the adapter owns a statusLine settings key and points it at the universal statusline entrypoint. The connector author edits the defineStatusline code above, not this generated settings leaf. Options are mapped only when the host capability says the native setting supports them.

{
  "statusLine": {
    "type": "command",
    "command": "agent-connector statusline claude-code --connector acme-db",
    "refreshInterval": 5
  }
}

Cross-validation for supported hosts#

The supported-host list below is not a marketing list. It is generated from adapters that set supportsStatusline, and each listed host must have a concrete write path plus tests that prove the configured command belongs to agent-connector.

Where it is wired today#

Public coverage metadata currently marks statusline support in 4 / 42 production-relevant adapters:

Claude Code, Droid (Factory), Antigravity CLI, Qwen CLI

Customization checklist#

• Keep the top-level render(ctx) as the universal fallback.
• Add hosts.<id>.render only when one host exposes better or different metadata.
• Use options for common intent and hosts.<id>.optionswhen one host supports extra statusline settings.
• Read ctx.usage for this connector's own recorded MCP usage; read ctx.context only for host-provided context-window state.
• Return an empty or simple string on missing data. A statusline should fail quiet, unlike a user-invoked action.

Design rules for beginners#

• Make the first version a single stable sentence or compact counter.
• Keep it useful without interaction. Actions belong in the actions surface, not in statusline text.
• Never put secrets, raw prompts, or raw tool arguments in a HUD.