Poke AI

What a poke is

Press Poke AI on a job or on an expanded bug, task, question, or suggestion to send that item to a connected coding agent. The message names its short code, so you can see which work was requested.

Keep the intended client session running and connected through Uclusion MCP. Codex selects one conversation; Claude Code and Cursor use their active listeners. The sections below explain how to choose the receiving session.

Claude Code

Keep the connected Claude Code session open. The installed integration uses a background listener to receive Pokes and replies from Uclusion.

If delivery is not running, type the item’s short code into the conversation to continue directly. After installing or updating Uclusion, restart Claude Code to load the configuration.

Cursor IDE chat

Send a message in the Cursor chat where you want to receive Pokes. Its listener follows the chat you last typed in, so changing chats can change the recipient.

If a Poke does not start a response, type the relevant short code in that chat and ask the agent to continue. Ask for find_work when you want to choose different work.

Automatic responds

Replying to the AI, voting on an option, or resolving its assistance sends a Responded message automatically. You can answer in Uclusion without copying the response into chat or pressing Poke AI again.

For a job waiting on a question, check its current assignees. Questions explains which responses can unblock the job and what Resolve delegates.

Automatic events for collaborators

Once an AI has participated in a job, Uclusion sends it notices of human changes to that work. These include new or edited discussion items, description and assignment changes, stage changes, and changes to the current design note.

These updates support work already in progress. To request work on a different item, use its Poke AI control or name its short code in the intended chat.

Codex receives Pokes through its native queue

Start ordinary Codex after installing or updating the Uclusion MCP integration:

codex

Codex CLI 0.160.0 or newer is required. New Pokes go to the latest eligible connected conversation in the configured workspace and environment. A busy conversation receives the message during its turn; a running command continues.

Start a turn in the conversation you want to receive Pokes, then inspect the selection from your project:

uclusion codex-recipients
# For a stage installation:
uclusion -e stage codex-recipients

The output shows conversation UUIDs, names, active or idle status, the selected recipient, and outstanding receipt checks. Inspection sends no input. Saved history alone does not make a conversation eligible, so check the selection after restarting or resuming Codex.

Retained history and existing installations

A fresh startup begins with new events. To request a private replay of retained history, add "--deliver-existing-pokes" to the args array in the installed [mcp_servers.uclusion] table. Use the project’s .codex/config.toml for a project installation, or your Codex home’s config.toml for a global install. Start a fresh codex session and remove the argument when replay is no longer wanted.

For an older installation that used uclusion codex, run uclusion update from the project directory, then fully exit and start codex. Use the environment-correct update, such as uclusion -e stage update, for a non-production installation.

Known issues

Codex can remain silent after accepting input. If the chat shows work without producing output, interrupt the turn and type continue in that conversation. Check its status before pressing Poke AI again for the same item; the original message may already have arrived.

How uclusion listen and uclusion wait work

These commands expose the local Poke stream for custom terminal integrations. Use the same environment flag as other CLI commands, for example uclusion -e stage listen.

• uclusion listen prints messages as they arrive and runs until stopped. --max-seconds <seconds> sets a limit; starting a limited listener stops other listeners started with that flag. On reaching the limit, it prints Uclusion listener rearm with its consumer name, which a custom harness can pass back through --consumer.
• uclusion wait --timeout <seconds> prints pending messages and exits. A quiet exit means its timeout expired without a new message.

Messages remain in the local queue for seven days. Each consumer tracks its own position, so reading a message does not remove another consumer’s copy. Set --consumer <name> or UCLUSION_CONSUMER when you need a stable identity across restarts. A bare uclusion wait outside Claude Code uses the shared default consumer.

Both commands also check for a new Uclusion release about every fifteen minutes. They print a one-time update notice; wait exits after the notice while listen continues until stopped or its limit is reached.

Starting without an old backlog

Fresh sessions begin with new events. For a custom terminal consumer using a bare uclusion wait, --ignore-existing-pokes skips the existing backlog. Skipping advances only that consumer’s cursor; it deletes no messages and does not affect other consumers.

Use --deliver-existing-pokes when you want a private replay of retained history. See the Codex configuration above for enabling replay in that client.

Multi-agent by default

Give each agent conversation a clear job or bug to work on. For a particular recipient, select the work directly in that conversation. Codex sends each new Poke to one selected conversation; active Claude Code and Cursor listeners can each receive a copy.

For a custom listener that needs an identity across restarts, set UCLUSION_CONSUMER or pass --consumer <name>. Distinct consumers keep their own positions in the event stream.

When agents choose work themselves, enable the work claim lock below to coordinate selection across sessions and machines.

The opt-in work claim lock

Enable work claims when several agents select work from the same workspace. The lock helps them select work that is not already claimed by another agent. It is off by default.

uclusion update --work-claims

Disable it with uclusion update --no-work-claims. For a non-production environment, put its option first, for example uclusion -e stage update --work-claims. Restart the affected clients or reconnect their Uclusion MCP servers to load the setting.

Claims are associated with live connections. They are released at a handoff or clean exit and expire after a disconnected agent stops refreshing them. If a crashed agent appears to hold work, allow time for the claim to expire and check the available-work list again.