Poke AI

What a poke is

Every job has a Poke AI button in its right side panel, and every unresolved bug, task, grouped task, question, and suggestion shows a compact Poke AI control in its expanded header. Pressing one sends the message Start <short code> — for example Start J-6 — to the AI terminals connected through the Uclusion MCP proxy. Your agent receives the message through uclusion listen or uclusion wait, loads the item with get_job, and begins the workflow without you typing anything in its chat.

Automatic responds

You do not need to poke after answering the AI. When the last item the AI is waiting on in a job moves out of Unresponded — you replied to its question or suggestion, voted on an option, resolved the item, or changed what it was blocked on — Uclusion automatically sends Responded <short code> naming what you responded on (releases before mid-2026 sent a bare Responded.). The waiting agent reloads that item and continues on its own.

How uclusion listen and uclusion wait work

The MCP proxy keeps a websocket subscription open for your account and writes every inbound prompt into a local, user-private queue on your machine (~/.uclusion/poke_inbox.sqlite3), de-duplicated by message id so broadcast and retry copies deliver once. Two commands read that queue, both polling it every quarter second and taking the same environment flag as every other CLI command:

• uclusion listen never exits. It prints each prompt as one line the moment it arrives, so an AI harness that can raise a running command’s output lines as events (such as Claude Code’s persistent Monitor) is woken per prompt with no restart between deliveries. Prefer this form wherever the harness supports it.
• uclusion wait --timeout <seconds> is for harnesses that only receive a command’s output when it exits (for example uclusion -e stage wait --timeout 3600). When at least one prompt is pending it prints the whole pending backlog, one prompt per line, and exits, so a burst of pokes costs a single wait; exiting silently means the timeout expired with nothing new.

While idle both commands also check about every fifteen minutes whether a newer Uclusion release is available and print a one-time update notice when they first see one — wait exits after printing it, while listen keeps running.

Prompts are not removed when they are read. They stay in the queue until they age out after seven days, and delivery tracks what has already been handed out with a named cursor (the --consumer option below, shared by both commands). That means an agent can never permanently lose a message by being restarted, and multiple agents can each see the full stream.

The form of the messages

The message text is the contract, and the first word tells you which kind arrived:

A poke always begins Start and a respond always begins Responded. Agents and any scheme you build on top of the queue can rely on that prefix. (Very old releases may still deliver a bare Responded. with no short code.)

Multi-agent is your scheme

Out of the box the queue is tuned for one agent: every listen or wait that omits --consumer shares one default cursor, so each prompt is delivered to exactly one listening agent — whichever polled first — and the installed workflow files tell agents not to worry about other agents at all.

If you run several agents against the same workspace, distributing that work is your responsibility, and the building block Uclusion gives you is consumer names. Launch each agent’s listener with --consumer <name> (on either command) and every distinct name receives every prompt exactly once, in order. For example, you could tell one leader agent to act on Start pokes and distribute the work while every agent checks each Responded message to see whether the short code is one it is working on. Uclusion does not referee beyond that — agents stepping on each other’s work, and agents that are stopped and restarted mid-scheme, are yours to manage through the instructions you give them.