Kiri Developers

WINDOW PLACES

Status bar note

A plugin can keep one note in the status bar along the bottom of Kiri’s window: its mark, up to 24 characters and a tone. A click on the note opens a small panel with up to five lines and two buttons. This page is the author’s side of it: the key that asks for the note, the calls that set it, and the limits Kiri holds it to. What people see, and how they hide a note, will be in the Kiri docs under Status bar notes when 1.0 ships.

Kiri
DockerContainersComposeImagesKiriSharePluginsSettings

Compose

▾ shop3 of 3 runningDeploying to prod
webnginx:1.27Up 2 hours
apishop-api · built hereUp 2 hours
Kiri 1.0.0Terminal2 shared tailnet · online shop → prod · 3 of 5VM running3 of 3 runningFeedback
Two plugin notes in the status bar. Kiri places them after its share count and before the VM's state, in the order they were installed, and draws each one from three things the plugin sent: text, a tone and the plugin's mark.

Ask for it

The note is a place in the window, so it’s a permission of its own. List it under [window] in kiri-plugin.toml:

[window]
status = true

The install prompt shows it as its own line: Show a note in the status bar. A plugin that calls kiri.status.set without the key gets a RefusedError naming that line, and the refusal goes in the person’s activity record. kiri plugin dev prints it the moment it happens.

Set and clear the note

Set the note from any handler: a deploy, a share, a check, or an event you listen for. Clear it when there’s nothing to say, and it leaves the bar. Coolify shows a note only while a deploy runs:

No Python version · showing TypeScript
await kiri.status.set({
  text: "shop → prod · 3 of 5",
  tone: "plain",
  lines: ["shop → prod: deploying", "web running · api running", "db starting"],
  buttons: [
    { label: "Open Deploys", page: "Deploys" },
    { label: "Open in Coolify", url: "https://coolify.example.com" },
  ],
});

// When the deploy is live, or has failed:
await kiri.status.clear();
err := k.Status.Set(plugin.Note{
	Text:  "shop → prod · 3 of 5",
	Tone:  "plain",
	Lines: []string{"shop → prod: deploying", "web running · api running", "db starting"},
	Buttons: []plugin.Button{
		{Label: "Open Deploys", Page: "Deploys"},
		{Label: "Open in Coolify", URL: "https://coolify.example.com"},
	},
})

// When the deploy is live, or has failed:
err = k.Status.Clear()
kiri.status().set(Note {
    text: "shop → prod · 3 of 5".into(),
    tone: Tone::Plain,
    lines: vec!["shop → prod: deploying".into(), "web running · api running".into(), "db starting".into()],
    buttons: vec![
        Button::new("Open Deploys", Where::Page("Deploys".into())),
        Button::new("Open in Coolify", Where::Url("https://coolify.example.com".into())),
    ],
}).await?;

// When the deploy is live, or has failed:
kiri.status().clear().await?;
Field What it is Limit
text The words in the bar, and the first line of the panel 24 characters. Longer text is cut and ends with “…”
tone plain, good, warning or bad. Kiri colours the text with its own colours for each Four tones, no colours of your own
lines The panel’s lines, under the plugin’s name Five
buttons Each one opens a page or a tab of the plugin, runs one of its actions, or opens a link: { label, page }, { label, tab }, { label, action } or { label, url } Two

A note is for state someone would otherwise have to go and look for: a deploy that’s running, a tailnet that went offline, a scan with critical findings. It isn’t a place for news or tips.

The panel a click opens

A click on the note only opens its panel, just above the bar. Kiri draws the panel from your lines and buttons, under your plugin’s mark and name. Nothing runs until a button is pressed, so a stray click can’t start a deploy.

Kiri
Coolify
shop → prod · 3 of 5shop → prod: deployingweb running · api runningdb starting
Open DeploysOpen in Coolify
Coolify's panel, drawn from the note above: the plugin's name, three lines, and two buttons. Open Deploys opens the plugin's Deploys page; Open in Coolify opens the link in the person's browser.

A button with action calls your plugin.action handler of that name, with no target. A url must be https or http, or a kiri:// address that opens a place in Kiri’s own window, such as kiri://images. See the Plugin API.

The rules

Rule Why
One note per plugin The bar is 24 pixels high and already full at narrow widths.
Up to 24 characters, cut with “…” It’s a glance, not a sentence. Leave room: words grow in German.
Four tones, coloured by Kiri A plugin can’t pass its note off as Kiri’s own VM state, or make it shout.
At most one change a second Kiri shows the newest text each second and skips the ones in between, so a busy plugin can’t make the bar flicker.
Three notes shown, the rest in +N Kiri’s own items never move, however many plugins someone adds. A note whose tone is bad is never folded: it takes the place of the last plain note.
Five lines and two buttons in the panel Anything bigger belongs on a page or tab.

While Kiri’s VM sleeps, the bar keeps the last note you sent, and a timer in your plugin doesn’t wake the VM. A plugin that’s switched off has no note, and the person can hide yours with a right-click while your plugin keeps working. Don’t put anything in the note that they’d need and can’t find elsewhere: the panel’s buttons should lead to a page, a tab or a link they can also reach from your plugin’s page.

See it, and test it

kiri plugin dev --outline draws a dashed line round your note with how much of its limit you use, such as A · 17 of 24. In tests, expect.status checks what your plugin left in the bar, and "" means no note. From the first plugin:

[[case]]
name = "a block counts in the note"
job = { check = "before-pull", image = "redis" }
expect = { verdict = "block", status = "1 blocked today" }
zsh
$ kiri plugin show no-latest
  no-latest 1.0.0 · from ./no-latest · on
  Note     1 blocked today  (warning)
  Shows in Check before pull, a note

kiri plugin show prints a plugin’s current note, so a script, or a server with no window, can read it too.

© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com