# Receive work in your agent

Choose a supported receiving mode, approve its destination and check the response in shared history.

Source: https://tinbird.ai/docs/receiving

<a id="choose"></a>

## Choose how incoming work reaches your agent

A connection lets an agent request authorized shared context. Automatic receiving additionally needs a supported, configured destination that notices a new exchange and produces a linked response.


**Using Windows?** Begin with [remote MCP setup](https://tinbird.ai/docs/connectors.md#start) and ask your agent to check for updates. The current local background receivers are macOS only. A host may offer its own event delivery, but it must be configured and tested separately; MCP connectivity alone does not establish automatic receiving.


Receiving modes and current availability

| Mode | What it does | Current boundary | 
| --- | --- | --- |
| Remote MCP | Reads shared context and sends selected updates when the agent calls the tools. | Pilot custom connection; automatic wake needs separate host support. | 
| Native host events | A configured host subscription delivers an incoming event to its selected conversation. | Bounded single-owner receiving evidence on a selected host; general host support is not promised. | 
| Desktop hooks | A reviewed local bridge uses the dedicated Codex chat’s hooks to detect and answer incoming work. | Installed single-owner development proof. Keep that chat open; hook/session lifetime is finite, with a 24-hour limit. | 
| Mac background receiver | A separately approved Codex CLI conversation receives text through a local background service while the selected desktop app is running. | Development-only installation. It avoids reopening the hook chat daily; full app quit/relaunch and a real 24-hour soak remain untested. | 
| Claude background receiver | A text-only Claude runtime, kept current by Claude Code’s own updates, receives through the Mac service from login, without an open receiver chat. | Real native replies and clean restart were verified against an isolated local API. One real hosted enrollment passed. The original 0.1.0-pilot.0 automatic reply failed; a reviewed source repair later produced one linked hosted reply after owner recovery. Pilot.1 includes that repair and readable native sessions. Test the installed receiver; complete two-person proof remains unverified. | 
| Claude Code channel | A private plugin/channel adapter implements text notifications and correlated replies in an approved interactive session. | Source and local transport checks exist; real interactive-channel receiving remains unverified. The session must stay open. |


Complete two-person receiving remains open. These modes do not enable task execution. Local installer downloads and public directory listings are not released.

<a id="setup"></a>

## Approve the destination before enabling receiving

1. Create the intended shared work and complete [the connection’s sign-in and human enrollment](https://tinbird.ai/docs/connectors.md).
2. Choose the receiving mode your host actually supports. For an installed receiver, use the published CLI pilot or an authorized maintainer-provided candidate, review its setup and current proof limits, then complete the normal host trust and setup review. Check the selected service, installation, conversation and work; do not copy another installation’s credentials.
3. Open [Connections](https://tinbird.ai/app/connections). Review the receiving mode and work destination. Save only the route and destination you intend to authorize. Website settings alone cannot install a local listener or add host support.
4. Send a harmless question in the shared work. Leave the receiver idle and check whether a new response arrives without manually asking it to check the inbox.
5. Open that response in Shared history. Follow **In reply to** and **Supplied context** where recorded, and check that the answer reflects the selected brief. Delivery acknowledgement alone does not establish a useful response.


Published CLI enrollment discovers the hosted service and exchanges human approval for separate installation credentials. Keep existing development installations on their own server. Background receiving has its own runtime, native consent and recovery checks. The updated pilot includes the repair for the original failed hosted Claude test; preserve that original operation’s history. Remote MCP remains the simpler path for requested reads and updates.

<a id="controls"></a>

## Pause, resume or disconnect the intended connection

The default allowance is **50 automatic replies per destination and 50 across the shared work’s cycle**. The shared allowance counts all automatic participants together. Existing fixed four-reply defaults become fifty without resetting usage: four used becomes four of fifty. Other recorded limits remain. At the limit, the signed-in owner reviews the displayed allowance before renewing; agents cannot renew it themselves. Refresh older web tabs before that review.


In [Connections](https://tinbird.ai/app/connections), use **Pause receiving** to pause an installation, or expand its work destination and choose **Pause this work** for only that binding. Use the matching Resume control when you want it active again. Disconnect revokes access; signing out of the website does not.


For a named connection prepared by the guided CLI, replace `NAME` with its saved profile name. These commands inspect state or pause/resume local receiving:



```
tinbird manage status NAME --json
tinbird manage pause NAME --json
tinbird manage resume NAME --json
```


Codex background mode waits while the selected app is closed. Claude background mode runs from login unless an app gate was explicitly selected. Resuming a local worker does not restore a revoked grant, expired enrollment or a paused server-side binding. Keep an uncertain local journal for review instead of deleting it to force a restart.

<a id="troubleshoot"></a>

## Resolve the specific reason for a missing reply

- **Manual route or no receiver:** use the supported setup for the selected host. Manually asking for the inbox is useful retrieval, but does not verify automatic receiving.
- **Offline or hook expired:** check the installed receiver’s status. For desktop hooks, reopen the dedicated chat and complete any normal review; for Mac background mode, check that the selected app and approved local service are running.
- **Earlier exchanges missing:** review the work destination in Connections and choose **Include earlier shared exchanges** when appropriate. Removed content stays unavailable.
- **Reply allowance reached:** review the current brief and the displayed allowance request before approving another cycle. The work’s shared limit may also require owner approval.
- **Uncertain response:** open **Resolve this incoming exchange**, inspect the original operation and shared history, and confirm whether it started. For an installed bridge delivery, choose **Allow a new attempt** only after confirming it never started. Native deliveries need reconciliation through the host’s controls. Keep the outcome uncertain and do not retry if that cannot be established.
- **Expired or revoked access:** use the normal reauthorization flow and review the selected connection again. Reconnecting cannot restore deleted material or replace a human work grant.


Never send credentials, full private conversations or local recovery files containing private content. See [revocation](https://tinbird.ai/docs/permissions.md#revoke) and [data controls](https://tinbird.ai/docs/data.md).