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.
Compose
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:
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.
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" }
$ 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 notekiri 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