pks-agent-notch

A Mac-notch-style pill at the top centre of your Windows screen. Agents and tools on the same machine post cards to it; you see each card pop out for a few seconds, hover to see them all, and click a button to answer. The notch never takes focus from the window you are typing in, so an agent in a terminal you cannot see can still ask.

A card with fields is a question: the person types or picks the answer on the card itself, and the asking tool reads it back by id. Cards have a kind that sets the badge colour: spørgsmål (orange), opgave (amber), fakta and info (muted), svar (green), tilladelse (red). The pill reads ● <source> · N kort, or ● <source> · 1 spørgsmål · N kort while something waits for an answer.

Install

irm https://agentics.dk/install/pks-agent-notch.ps1 | iex
pks-agent-notch

Windows 10/11, x64. Self-contained single file; nothing else to install.

Run

A plain start prints nothing: the notch is a window without a console. What you should see is the pill at the top of the screen and a tray icon. When neither appears, read %LOCALAPPDATA%\pks-notch\notch.log — every start, exit and unhandled exception is a line there.

The demo

pks-agent-notch demo is the acceptance test, the product demo and a reference client in one. Ten scenes: health (the health document and the 404 route list), kinds (all six kinds live at once, then deleted), klik (you click one of two buttons — status and the SSE event must agree), luk (you close a tilladelse with ✕ → dismissed), ttl (ttl_s → expired), erstat (same id twice → one card, the first replaced in history), felter (a question with all five field types — you fill it in), svar-api (POST …/answer: 400 without the required value, 200 with it, 409 the second time), reply-to (a loopback listener receives the status; http://example.com is refused) and historik (every card of the run, with outcome and values). Pipe it from PowerShell (| Out-Host) or run it as pks exec pks-agent-notch demo — a window app otherwise hands the prompt back at once. Exit codes: 0 all passed · 1 a scene failed · 2 no notch to talk to · 3 bad flags.

Right-click the notch, or the tray icon: Dock top · Dock bottom · Afslut. Hover for the full list; the ✕ chip top-right hides the notch to a sliver until the next card (at least 10 s).

The API

While it runs, the notch serves http://127.0.0.1:<port>/ and writes the port to %LOCALAPPDATA%\pks-notch\port (one line; deleted on exit).

$port = Get-Content "$env:LOCALAPPDATA\pks-notch\port"
$base = "http://127.0.0.1:$port"

Asking a question

A card with fields is a question the person answers on the card: text (placeholder, suggestions, multiline), choice (one of), multi (any of), toggle (ja/nej), number (min/max). The submit action is dimmed until the required fields are filled; a secondary action ("Senere") sends whatever is there. Read the answer back from GET /v1/cards/{id}, the event stream, or give a reply_to URL (https:// anywhere, http:// only on this machine) and the notch POSTs the status when the card ends.

Invoke-RestMethod -Method Post -Uri "$base/v1/cards" -ContentType 'application/json' -Body '{
  "id":"voice-1","source":"heypoul","kind":"spørgsmål","title":"Hvem er det, der taler?",
  "text":"Ukendt stemme i 70 s.",
  "fields":[{"id":"name","type":"text","label":"Navn","required":true,"suggestions":["Anders Hjorth","Malthe Schou"]},
            {"id":"keep","type":"toggle","label":"Gem stemmen","default":true}],
  "actions":[{"id":"save","label":"Gem"},{"id":"later","label":"Senere"}],"ttl_s":900}'
Invoke-RestMethod "$base/v1/cards/voice-1"
# state: answered, answer: {action: save, values: {name: "Anders Hjorth", keep: true}}

Post a question and wait for the answer:

Invoke-RestMethod -Method Post -Uri "$base/v1/cards" -ContentType 'application/json' -Body '{
  "id":"q-1","source":"demo","kind":"spørgsmål","title":"Skal vi sende tilbuddet mandag?",
  "actions":[{"id":"yes","label":"Ja, mandag"},{"id":"later","label":"Senere"}],"ttl_s":120}'
curl.exe -sN "$base/v1/events"
# event: action
# data: {"card":"q-1","action":"yes","source":"demo"}

A click resolves the card (it leaves the list) before the event is sent; re-POST with the same id to keep it. English kind names (question, task, fact, answer, permission, info) are accepted and stored as the Danish ones. No auth in v0: loopback, same user.

The full contract with every status code is in the repo's docs/protocol.md.

Sources

• heypoul — the first source: insight cards from a live meeting transcript.
• Claude Code hooks — next: permission requests and questions from a coding agent.

Anything that can do an HTTP POST on the same machine is a source.