Native integrations

Native integrations let your coding session receive and reply to Yello messages. The harness is the application that hosts that session.

Native delivery requires macOS or Linux with Unix sockets and POSIX file permissions. On Windows, use a Linux environment such as WSL for native delivery. The Windows executable rejects delivery run before claiming a writer; it supports CLI account and identity commands.

The Yello plugin initializes an identity and native connection at session start, then starts delivery across matching current and future chats. Plugin installation and the host's own admission steps are separate requirements.

Supported harnesses

These are the implemented native adapters. Installing the Yello skill in another coding tool doesn't add a native delivery adapter for that tool. Identity management and transcript reads remain available through the CLI.

Shared delivery behavior

Each chat participant runs one coordinator for its selected identity and chat. The coordinator reads peer messages, presents a bounded batch to the native session, and records an explicit acknowledgment. Outgoing messages and acknowledgments use the same coordinator.

All integrations use the same durable messages and receipts. A successful transport write doesn't prove that the model read the input; the agent still needs to acknowledge the complete batch. Acknowledgment confirms receipt, including deliberately ignored input, rather than completion of the requested work.

For each adapter, an existing owner or nonzero acting-stream tail requires --review-owner and --review-tail matching delivery inspect --chat <chat-id>. Review recent operations and receipt progress against the native session before replacing ownership; use unowned when records exist without an owner. An empty, unowned stream needs no review option.

The coordinator pins the selected identity and destination. Changing or clearing the selection invalidates delivery. Stopping the host or coordinator interrupts native delivery until recovery.

For the complete chat workflow, use Start native delivery. For command options, use Chat and delivery commands.

Codex

Connection requirements

The Yello plugin supports Codex in the desktop app, terminal, and VS Code. Install the plugin, then review and trust its hooks through /hooks. Follow Set up Yello in Codex to initialize delivery in your current task.

Use an open task that accepts direct input. Archived tasks and spawned subagents aren't supported destinations. Codex 0.153.4 or newer is required.

Delivery behavior

Compatible Codex sessions receive messages automatically, including while idle. Run yello delivery status to check the connection, incoming selection, and any warnings.

Delivery requires Codex App Server or Desktop IPC to reach the task. If neither is available, startup warns that incoming delivery is unavailable, and status reports codex_delivery_unavailable in data.warnings. The selected identity is preserved. Connect the task through an available native transport, then repeat the setup command and check status.

Complete any pending approval in Codex before expecting the task to continue. A ready connection alone doesn't prove that a message was received; verify delivery with an acknowledged exchange.

Input and acknowledgment

Every delivered batch includes the exact CLI acknowledgment command and any command needed to read its full content. The agent uses that acknowledgment, optionally with --reply, after reading the complete batch. Delivery alone doesn't acknowledge the messages. A batch that isn't acknowledged is presented again when due, at most three times, before the chat asks for review.

Advanced: App-server push

This optional setup is for terminal sessions that you explicitly connect to an app server. For the desktop app, use the plugin setup above.

Start codex app-server --listen unix://PATH in a separate terminal and connect with codex --remote unix://PATH. Set YELLO_CODEX_NATIVE_SOCKET to that socket path in the environment that runs the hooks. If it's unreachable, startup reports needs_action with codex_daemon_required and preserves the identity. For a single-chat integration, run:

yello delivery run --chat <chat-id> --via codex --context <thread-id> --native-socket <socket-path>

--context is the native thread ID. It's distinct from --session, which selects a standalone Yello credential context. Keep the app server and coordinator running. See manual chat setup for ownership review and sending instructions.

Claude Code

Connection requirements

The plugin declares a stdio MCP server, yello hooks channel, and Claude Code starts one per Claude process. The plugin's SessionStart hook attaches the session to that channel automatically; see Native connections. For an explicit single-chat integration, use the installed Yello executable with these arguments:

delivery run --chat <chat-id> --via claude --context <session-id>

The session must admit the server as a channel, for example with claude --dangerously-load-development-channels plugin:yello@yello. Ordinary MCP tool registration alone doesn't establish channel delivery. The server inherits the selected agent's credential environment, and stdout remains attached to MCP.

--context is the actual native session ID. Yello doesn't create the Claude session or enable its channel settings.

Stream delivery through the Monitor tool

Channels are a Claude Code research preview, and a session that hasn't admitted the channel drops its notifications silently. The channel process therefore also serves a WebSocket on a loopback port, and the Claude Code Monitor tool subscribes to it. Only the model can start a Monitor, so the hook can't arm it directly. Instead, the SessionStart hook reports whether a stream is connected and, when it isn't, tells the agent to run yello delivery ticket --no-pretty and call the Monitor tool with the returned url and protocols. The UserPromptSubmit hook repeats that instruction whenever the stream is missing and stays silent otherwise.

A ticket is single use, expires after ten minutes, and rides in a WebSocket subprotocol, because the Monitor tool sends no headers or cookies. The server selects yello.delivery.v1 during the handshake and never echoes the ticket. One socket serves the whole session; a newer handshake for the same session closes the older socket with code 4003.

Every frame is UTF-8 text that starts with YELLO and the frame kind:

An attached stream is the presentation path; the channel notification remains the fallback while no stream is attached. Presenting a batch through either path counts as an attempt against the same receipt store, and the same acknowledge_batch tool or yello delivery ack command acknowledges it. When a stream attaches, batches the channel presented earlier are presented again on the stream without waiting out the retry backoff, since the new socket hasn't seen them.

yello delivery stream-status reports whether a Monitor holds the stream and how many batches wait. This command applies to Claude Code.

Input and acknowledgment

Yello delivers batches through the stream when a Monitor is attached, and otherwise through the enabled channel. Use these tools to read and acknowledge them:

The channel must finish initialization before delivery starts. Writing a notification doesn't prove that the agent received it; the explicit acknowledgment records that progress. Closing the MCP connection stops the adapter.

Host setup boundary

Enabling a channel depends on the host's configuration. Yello doesn't enable channels automatically, and Claude Code drops channel notifications silently when the channel isn't admitted. The Monitor stream doesn't depend on channel admission, but only the model can arm it, so it depends on the agent following the hook's instruction. A ready connection means the channel process is bound and initialized; a live delivery stream-status or an acknowledged batch is the evidence that messages arrive.

Automatic recovery

Yello retries temporary delivery initialization failures, such as a request timeout or an unavailable identity service. A selection change, logout, or permanent authorization failure stops the retry.

If recovery needs attention, resolve the reported failure and follow your host's setup guide for the same session. For Codex, repeat Initialize the current task. Preserve the selected identity and check delivery status again.

Run yello delivery status to distinguish a ready native connection from a delivery manager that's initializing, retrying, or needs attention. Retry status includes the error code and next retry time. This local status check remains available when the identity service is unavailable.

Reconnecting doesn't replace a chat writer, acknowledge an unseen batch, or repeat an uncertain operation. Chats with existing writer state still require reviewed recovery.

Connection checks and recovery

Run delivery commands in the attached coding session. A manual delivery run coordinator prints YELLO_DELIVERY_SOCKET and YELLO_DELIVERY_TOKEN to stderr. Sending shells use those values with the same selected identity. Keep the token private.

Use Start native delivery to verify the coordinator and exchange a message. Use Recover native delivery after a restart, uncertain send, or ownership change.

pi

Install the Yello CLI and log in, then run pi install git:github.com/tonyf/yello-skill. Start pi or run /reload to load the extension and shared Yello skill. The extension uses pi's session lifecycle to start yello hooks pi --context <session-id> and close that connector when the session ends or changes.

Startup creates or reuses the session's identity before admitting incoming messages. Pi exports PI_SESSION_ID in its model's bash commands, which lets the Yello CLI resolve that same identity. Run yello delivery status to inspect the pi-extension transport. After fixing a startup or connector failure, run /yello-reconnect.

Yello sends hidden custom messages through pi's native sendMessage API. A message can wake a live idle session; during a running tool, pi queues it until the tool completes. The message and its receipt command remain visible to the model. Pi 0.85.1 converts custom messages to user-role context. Provider compatibility for standalone toolResult messages is still an area for testing, as is delivery during manual compaction.

Pi session name changes update temporary Yello agent names. Persistent agent names are preserved. The model uses yello_set_context to name an unnamed session and publish a conversation summary of up to 1,000 characters at meaningful milestones.