Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

feat(coding-agent): add /speed command showing output tok/sec in the footer (#2466)

Seth Karteneee9d814b203
diff --git a/packages/coding-agent/.changes/tui-speed-command.md b/packages/coding-agent/.changes/tui-speed-command.md
new file mode 100644
index 0000000000..4f72e0e300
--- /dev/null
+++ b/packages/coding-agent/.changes/tui-speed-command.md
@@ -0,0 +1 @@
+- Added the `/speed [on|off]` session command: toggles a compact footer readout of model output tok/sec (latest response plus session average), computed from existing stream events with no provider protocol changes.
diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index 6ec2c9923c..dfe1a5b4dc 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -161,6 +161,7 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
| `/session` | Show session info (file, ID, messages) |
| `/traces [status\|on\|off\|preview\|upload-current\|upload-all\|login]` | Preview traces, run one-shot current/all uploads, and manage automatic sharing (`upload` aliases `upload-current`) |
| `/usage` | Show token, cost, and context usage |
+| `/speed [on\|off]` | Toggle footer readout of model output tok/sec (latest response and session average) |
| `/tree` | Jump to any point in the session and continue from there |
| `/fork` | Create a new session from a previous user message |
| `/clone` | Duplicate the current active branch into a new session |
diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.md
index 0307486b0e..e55009437b 100644
--- a/packages/coding-agent/docs/usage.md
+++ b/packages/coding-agent/docs/usage.md
@@ -48,6 +48,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
| `/session` | Show session file, ID, and message counts |
| `/traces [status\|on\|off\|preview\|upload-current\|upload-all\|login]` | Preview, upload, or manage opt-in trace sharing |
| `/usage`, `/context` | Show the parent and subagent context, token, and cost breakdown |
+| `/speed [on\|off]` | Toggle footer readout of model output tok/sec (latest response and session average) |
| `/tree` | Jump to any point in the session and continue from there |
| `/fork` | Create a new session from a previous user message |
| `/clone` | Duplicate the current active branch into a new session |
diff --git a/packages/coding-agent/src/core/slash-commands.ts b/packages/coding-agent/src/core/slash-commands.ts
index 4d93bc30af..4243ab59dc 100644
--- a/packages/coding-agent/src/core/slash-commands.ts
+++ b/packages/coding-agent/src/core/slash-commands.ts
@@ -212,6 +212,12 @@ const CANONICAL_BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
argumentHint: "[on|off]",
takesArgument: true,
},
+ {
+ name: "speed",
+ description: "Toggle footer readout of model output tok/sec (latest response and session average)",
+ argumentHint: "[on|off]",
+ takesArgument: true,
+ },
{ name: "quit", description: `Quit ${APP_NAME}` },
];
diff --git a/packages/coding-agent/src/modes/interactive/components/footer.ts b/packages/coding-agent/src/modes/interactive/components/footer.ts
index a8afd00ebe..b0d468f643 100644
--- a/packages/coding-agent/src/modes/interactive/components/footer.ts
+++ b/packages/coding-agent/src/modes/interactive/components/footer.ts
@@ -1,5 +1,6 @@
-import type { Component } from "@earendil-works/pi-tui";
+import { type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
import type { ReadonlyFooterDataProvider } from "../../../core/footer-data-provider.js";
+import { theme } from "../theme/theme.js";
/**
* Footer component for the prime brand TUI.
@@ -7,9 +8,13 @@ import type { ReadonlyFooterDataProvider } from "../../../core/footer-data-provi
* Renders nothing by default — token counters, cost, model name, cwd, and context %
* are intentionally hidden. The setters and invalidate/dispose hooks are kept so the
* existing call sites in interactive-mode keep working without modification, and so
- * `/usage` can expose telemetry without re-plumbing.
+ * `/usage` can expose telemetry without re-plumbing. `/speed` opts the footer into a
+ * compact tok/sec readout; see setSpeedEnabled/setSpeedText.
*/
export class FooterComponent implements Component {
+ private speedEnabled = false;
+ private speedText: string | undefined;
+
constructor(private footerData: ReadonlyFooterDataProvider) {
void this.footerData;
}
@@ -18,6 +23,19 @@ export class FooterComponent implements Component {
// no-op while the footer is empty
}
+ /** /speed toggle: when enabled, render the tok/sec text set via setSpeedText. */
+ setSpeedEnabled(enabled: boolean): void {
+ this.speedEnabled = enabled;
+ if (!enabled) {
+ this.speedText = undefined;
+ }
+ }
+
+ /** Latest tok/sec readout computed by interactive-mode from completed model responses. */
+ setSpeedText(text: string | undefined): void {
+ this.speedText = text;
+ }
+
/**
* No-op: git branch caching now handled by provider.
* Kept for compatibility with existing call sites in interactive-mode.
@@ -34,9 +52,11 @@ export class FooterComponent implements Component {
// Git watcher cleanup handled by provider
}
- render(_width: number): string[] {
- // Footer is intentionally empty in the prime brand TUI. Telemetry (cost, tokens, model,
- // cwd, context %) is hidden by default; bring it back via /usage when needed.
- return [];
+ render(width: number): string[] {
+ if (!this.speedEnabled || !this.speedText) {
+ return [];
+ }
+ const text = visibleWidth(this.speedText) > width ? truncateToWidth(this.speedText, width, "") : this.speedText;
+ return [theme.fg("dim", text)];
}
}
diff --git a/packages/coding-agent/src/modes/interactive/interactive-mode.ts b/packages/coding-agent/src/modes/interactive/interactive-mode.ts
index adacbe7dcf..788ade0d31 100644
--- a/packages/coding-agent/src/modes/interactive/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive/interactive-mode.ts
@@ -1152,6 +1152,10 @@ export class InteractiveMode {
// wraps the active footer so custom-footer swaps reflect in both layouts
private footerSlot: Container;
private fullscreenEnabled = false;
+ // /speed state: display flag plus per-session output tok/sec tracking (see recordSpeedSample).
+ private speedDisplayEnabled = false;
+ // Accumulated output-token/duration totals; allocated on the first recorded sample.
+ private speedStats: { tokens: number; durationMs: number; samples: number } | undefined;
private editorContainer: Container;
private footer: FooterComponent;
private footerDataProvider: FooterDataProvider;
@@ -3305,6 +3309,10 @@ export class InteractiveMode {
private async rebindCurrentSession(): Promise<void> {
this.unsubscribe?.();
this.unsubscribe = undefined;
+ // Sessions are independent: a rebind (new/resume/switch) restarts tok/sec stats
+ // and clears the readout left over from the previous session.
+ this.speedStats = undefined;
+ this.footer?.setSpeedText?.(undefined);
void this.rosterBar?.dispose();
this.rosterBar = undefined;
if (this.localSessionHost) {
@@ -5424,6 +5432,17 @@ export class InteractiveMode {
this.setFullscreenMode(enable);
return;
}
+ if (commandName === "speed") {
+ this.editor.setText("");
+ const arg = commandArgs?.trim().toLowerCase();
+ if (arg && arg !== "on" && arg !== "off") {
+ this.showError("Usage: /speed [on|off]");
+ return;
+ }
+ const enable = arg === "on" ? true : arg === "off" ? false : !this.speedDisplayEnabled;
+ this.setSpeedDisplay(enable);
+ return;
+ }
if (commandName === "debug") {
if (commandArgs) {
this.editor.setText(text);
@@ -6127,6 +6146,7 @@ export class InteractiveMode {
component.setArgsComplete();
}
}
+ this.recordSpeedSample(event.message);
this.streamingComponent = undefined;
this.streamingMessage = undefined;
this.footer.invalidate();
@@ -7916,6 +7936,56 @@ export class InteractiveMode {
);
}
+ /** /speed on/off: toggles the footer tok/sec readout for this session. */
+ private setSpeedDisplay(enabled: boolean): void {
+ this.speedDisplayEnabled = enabled;
+ if (!enabled) {
+ this.resetSpeedStats();
+ }
+ this.footer.setSpeedEnabled(enabled);
+ this.showStatus(
+ enabled
+ ? "Speed display on — footer shows output tok/s per model response and a session average"
+ : "Speed display off",
+ );
+ this.ui.requestRender();
+ }
+
+ /** Clears per-session tok/sec stats and the footer readout; keeps the display flag. */
+ private resetSpeedStats(): void {
+ this.speedStats = undefined;
+ this.footer.setSpeedText(undefined);
+ }
+
+ /**
+ * Updates the footer tok/sec readout from a completed assistant message:
+ * output tokens over the wall-clock span from the message timestamp (set at
+ * provider stream start) to this message_end arrival. Timestamps keep the span
+ * true even when buffered session events replay back-to-back on attach.
+ * Aborted/failed responses and samples without a finite positive span or token
+ * count are skipped: some providers only fill usage at stream end, and extension
+ * message replacements may strip fields, so they never produce a bogus rate.
+ */
+ private recordSpeedSample(message: AssistantMessage): void {
+ if (!this.speedDisplayEnabled || message.stopReason === "aborted" || message.stopReason === "error") {
+ return;
+ }
+ const durationMs = Date.now() - Number(message.timestamp);
+ const outputTokens = Number(message.usage?.output ?? 0);
+ if (!(durationMs > 0) || !(outputTokens > 0)) {
+ return;
+ }
+ this.speedStats ??= { tokens: 0, durationMs: 0, samples: 0 };
+ this.speedStats.tokens += outputTokens;
+ this.speedStats.durationMs += durationMs;
+ this.speedStats.samples++;
+ const formatRate = (tokensPerSecond: number): string =>
+ tokensPerSecond >= 100 ? tokensPerSecond.toFixed(0) : tokensPerSecond.toFixed(1);
+ const last = formatRate(outputTokens / (durationMs / 1000));
+ const average = formatRate(this.speedStats.tokens / (this.speedStats.durationMs / 1000));
+ this.footer.setSpeedText(this.speedStats.samples > 1 ? `${last} tok/s · avg ${average}` : `${last} tok/s`);
+ }
+
private toggleToolOutputExpansion(): void {
this.setChatDetail(this.toolOutputExpanded ? "overview" : this.editDiffsExpanded ? "all" : "details");
}
diff --git a/packages/coding-agent/test/interactive-mode-command-usage.test.ts b/packages/coding-agent/test/interactive-mode-command-usage.test.ts
index 36611605e7..ff910ae15e 100644
--- a/packages/coding-agent/test/interactive-mode-command-usage.test.ts
+++ b/packages/coding-agent/test/interactive-mode-command-usage.test.ts
@@ -82,4 +82,21 @@ describe("InteractiveMode no-argument command usage errors", () => {
expect(context.showError).toHaveBeenCalledWith(`Usage: /${command}`);
expect(prompt).not.toHaveBeenCalled();
});
+
+ it("toggles /speed on and off, parses explicit args, and rejects invalid arguments", async () => {
+ const context = makeSubmitContext();
+ Object.setPrototypeOf(context, InteractiveMode.prototype); // runs the real setSpeedDisplay
+ const footer = { setSpeedEnabled: vi.fn(), setSpeedText: vi.fn() };
+ Object.assign(context, { footer, speedDisplayEnabled: false });
+ Object.assign(context, { ui: { requestRender: vi.fn() }, uiServices: { settingsManager: {} } });
+ prototype.setupEditorSubmitHandler.call(context);
+ await context.defaultEditor.onSubmit?.("/speed");
+ expect(footer.setSpeedEnabled).toHaveBeenLastCalledWith(true);
+ await context.defaultEditor.onSubmit?.("/speed off");
+ expect(footer.setSpeedEnabled).toHaveBeenLastCalledWith(false);
+ expect(footer.setSpeedText).toHaveBeenCalledWith(undefined);
+ await context.defaultEditor.onSubmit?.("/speed banana");
+ expect(context.showError).toHaveBeenCalledWith("Usage: /speed [on|off]");
+ expect((context.agentConnection as { prompt: ReturnType<typeof vi.fn> }).prompt).not.toHaveBeenCalled();
+ });
});
diff --git a/packages/coding-agent/test/interactive-mode-streaming.test.ts b/packages/coding-agent/test/interactive-mode-streaming.test.ts
index 4458a6f4ad..7f16ea7fa6 100644
--- a/packages/coding-agent/test/interactive-mode-streaming.test.ts
+++ b/packages/coding-agent/test/interactive-mode-streaming.test.ts
@@ -1,11 +1,13 @@
import type { AssistantMessage, Usage } from "@earendil-works/pi-ai";
import { Container, type MarkdownTheme, type TUI } from "@earendil-works/pi-tui";
import stripAnsi from "strip-ansi";
-import { beforeAll, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+import type { ReadonlyFooterDataProvider } from "../src/core/footer-data-provider.js";
import type { AgentConnectionSessionEvent } from "../src/modes/agent-connection/index.js";
import { AgentActivityTracker } from "../src/modes/interactive/agent-activity.js";
import type { AssistantMessageComponent } from "../src/modes/interactive/components/assistant-message.js";
import type { FileChangeSummary } from "../src/modes/interactive/components/edit-summary.js";
+import { FooterComponent } from "../src/modes/interactive/components/footer.js";
import type { ToolExecutionComponent } from "../src/modes/interactive/components/tool-execution.js";
import { InteractiveMode } from "../src/modes/interactive/interactive-mode.js";
import { getMarkdownTheme, initTheme } from "../src/modes/interactive/theme/theme.js";
@@ -95,14 +97,14 @@ function createFakeInteractiveModeThis(): HandleEventThis {
return fakeThis;
}
-function createAssistantMessage(text: string): AssistantMessage {
+function createAssistantMessage(text: string, usage: Usage = EMPTY_USAGE): AssistantMessage {
return {
role: "assistant",
content: [{ type: "text", text }],
api: "test-api",
provider: "test-provider",
model: "test-model",
- usage: EMPTY_USAGE,
+ usage,
stopReason: "stop",
timestamp: Date.now(),
};
@@ -153,4 +155,45 @@ describe("InteractiveMode streaming events", () => {
expect(fakeThis.streamingComponent).toBeUndefined();
expect(fakeThis.streamingMessage).toBeUndefined();
});
+ describe("speed display tok/sec tracking", () => {
+ const speedLine = (footer: FooterComponent) => stripAnsi(footer.render(200).join("\n"));
+ const makeSpeedThis = (enabled = true) => {
+ const fakeThis = createFakeInteractiveModeThis();
+ const footer = new FooterComponent({ getGitBranch: () => null } as ReadonlyFooterDataProvider);
+ footer.setSpeedEnabled(enabled);
+ Object.assign(fakeThis as Record<string, unknown>, { footer, speedDisplayEnabled: enabled });
+ return { fakeThis, footer };
+ };
+ const speedPrototype = InteractiveMode.prototype as unknown as {
+ handleEvent(this: Record<string, unknown>, event: AgentConnectionSessionEvent): Promise<void>;
+ recordSpeedSample(this: Record<string, unknown>, message: AssistantMessage): void;
+ };
+ afterEach(() => vi.restoreAllMocks());
+ test("records output tok/s per completed assistant message with a session average", async () => {
+ const { fakeThis, footer } = makeSpeedThis();
+ const now = vi.spyOn(Date, "now").mockReturnValue(1_000);
+ const first = createAssistantMessage("first", { ...EMPTY_USAGE, output: 100, totalTokens: 100 });
+ now.mockReturnValue(3_000);
+ await speedPrototype.handleEvent.call(fakeThis, { type: "message_end", message: first });
+ expect(speedLine(footer)).toBe("50.0 tok/s");
+ const second = createAssistantMessage("second", { ...EMPTY_USAGE, output: 300, totalTokens: 300 });
+ now.mockReturnValue(5_500);
+ await speedPrototype.handleEvent.call(fakeThis, { type: "message_end", message: second });
+ expect(speedLine(footer)).toBe("120 tok/s · avg 88.9");
+ });
+ test.each<[string, boolean, number, number, string, Record<string, unknown>]>([
+ ["zero output tokens", true, 0, 2_000, "9.9 tok/s", { timestamp: 1_000 }],
+ ["zero duration", true, 100, 0, "9.9 tok/s", {}],
+ ["aborted message", true, 50, 2_000, "9.9 tok/s", { stopReason: "aborted", timestamp: 1_000 }],
+ ["stripped usage and timestamp", true, 100, 2_000, "9.9 tok/s", { usage: undefined, timestamp: undefined }],
+ ["display disabled", false, 100, 2_000, "", {}],
+ ])("skips the sample when %s", (_label, enabled, output, durationMs, expected, overrides) => {
+ const { fakeThis, footer } = makeSpeedThis(enabled);
+ footer.setSpeedText("9.9 tok/s");
+ vi.spyOn(Date, "now").mockReturnValue(1_000 + durationMs);
+ const message = Object.assign(createAssistantMessage("partial", { ...EMPTY_USAGE, output }), overrides);
+ speedPrototype.recordSpeedSample.call(fakeThis, message);
+ expect(speedLine(footer)).toBe(expected);
+ });
+ });
});
diff --git a/packages/coding-agent/test/slash-commands.test.ts b/packages/coding-agent/test/slash-commands.test.ts
index e3c10c19f3..84cf453ffc 100644
--- a/packages/coding-agent/test/slash-commands.test.ts
+++ b/packages/coding-agent/test/slash-commands.test.ts
@@ -40,6 +40,8 @@ describe("slash command aliases", () => {
expect(builtinSlashCommandTakesArgument("thinking")).toBe(builtinSlashCommandTakesArgument("effort"));
expect(builtinSlashCommandTakesArgument("clear")).toBe(false);
expect(builtinSlashCommandTakesArgument("new")).toBe(true);
+ expect(BUILTIN_SLASH_COMMANDS.find((c) => c.name === "speed")?.argumentHint).toBe("[on|off]");
+ expect(BUILTIN_SLASH_COMMANDS.find((c) => c.name === "speed")?.takesArgument).toBe(true);
});
test("parses /new names, prompts, and option errors", () => {