Wake your agent instantly with the relay

A connected agent finds out about your comments by asking. On its own schedule it calls Onplana and says “anything new on the tasks I created?” That poll is reliable and works everywhere, but it means your feedback sits unread until the agent next gets around to checking.

The agent relay closes that gap. It is a small program you run next to your agent. It holds one connection open to Onplana and wakes your agent the moment something happens, so a comment you leave at 09:00 is picked up at 09:00 rather than at the next sync.

You do not need a server, a public URL, or any network configuration. The relay dials out to Onplana, so it works from a laptop behind a home router exactly as well as from a data centre.

You may not need this

The relay is a speed improvement, not a capability unlock. Everything your agent can do with the relay, it can already do without it, just more slowly. Start without it and add it when the waiting becomes annoying.

What it reacts to

Three things wake your agent:

Event	Fires when
comment.created	Someone comments on a task your agent created
comment.mention	Someone @mentions your agent on any task
task.run_requested	Someone selects Run with <agent> on a task

That is deliberately a short list. The relay is for the moments a human is waiting on the agent, not a firehose of everything happening in your organization. For broader automation, use webhooks.

Set it up

1. Connect your agent first. Follow Connect an external AI agent and keep the personal access token it gives you. The relay uses the same token, so there is nothing extra to authorize.

2. Make one call from your agent before starting the relay. Ask it something trivial, such as “which Onplana organization am I in?”. This registers the connection. If you skip it the relay reports No agent connection found for this PAT yet.

3. Start the relay, passing the token as an environment variable rather than a command-line flag, so it does not land in your shell history:

   ONPLANA_PAT=pat_xxx npx @onplana/agent-relay

   You should see it connect and then sit quietly. Quiet is correct. It prints a line per event, and nothing happens until something happens.

4. Point it at your agent with --provider. See the next section.

Use the API host, not the app host

The relay defaults to https://api.onplana.com, which is right for almost everyone. If you override it, use the API host and not app.onplana.com. The app host serves the web interface and does not carry the event stream, so a relay pointed there waits forever without an obvious error.

Connecting it to your agent

How the relay reaches your agent depends on whether you want it to start a run or notify a session you already have open. Those are different jobs and they need different providers.

Start a run for each event

--provider exec runs a command of your choosing every time an event arrives. This is the one to use if you want to leave work for your agent and walk away:

ONPLANA_PAT=pat_xxx npx @onplana/agent-relay \
  --provider exec --exec "claude -p"

The event reaches your command as JSON on its standard input, with the event name, task id and project id also in the environment. Runs are serialised, one at a time, so three comments arriving together do not start three agents over the same working copy.

Your command decides what is safe

Anyone who can comment in your organization can influence the content your command reads. They cannot influence which command runs: the relay builds it only from your own --exec string and never puts event text on the command line. Keep it that way by treating the JSON on standard input as data. Piping it into a shell hands that protection back.

Notify a session you already have open

--provider claude-code and --provider codex drop a small file into a folder your agent watches:

ONPLANA_PAT=pat_xxx npx @onplana/agent-relay \
  --provider claude-code --inbox ./.claude/inbox

Then give your session a standing instruction along the lines of “if files appear in .claude/inbox/, read each one, do what it describes, then move it to .claude/inbox/processed/”. Use --provider codex for Codex, which defaults to .codex/inbox instead.

The relay writes the files and leaves them alone. Moving them once handled is your agent’s job, which is what keeps the same event from being worked twice.

A dropped file is a mailbox, not a wake

These two providers write a file and stop. A session that is idle, or not running at all, never learns it arrived. That is the right trade when you are working alongside your agent and want events to reach the session you already have open, and the wrong one if you are leaving work for it. Use exec for that.

Anything else

The default log provider prints one JSON object per line, so you can pipe it into whatever you already use:

ONPLANA_PAT=pat_xxx npx @onplana/agent-relay | while read event; do
  ./wake-my-runner.sh "$event"
done

Prefer exec over this shape when you can. Here the event has become a shell variable, so keeping it out of trouble is now your problem; exec never lets it near a command line in the first place.

What clients use it for

These are the patterns worth setting up. All three events are dull on their own; the value is in what you connect them to.

Review-and-revise without the wait

Your agent drafts something, posts it, and you comment “the second section is wrong, we deprecated that last quarter”. Without the relay your correction sits until the next poll, and by then you have context switched to something else. With it the agent revises while you are still looking at the task.

This is the most common reason clients install it, and the one with the clearest payoff: it turns agent review from an inbox you process later into a conversation you finish now.

An agent that watches a queue

Point an agent at a project used for intake, whether that is bug reports, content requests, or support escalations, and have it triage each new item. A colleague comments a clarification, the agent updates its triage immediately. Nobody has to remember to nudge anything.

Handing work between a person and an agent

An analyst does the judgement part and leaves a comment saying which direction to take. The agent picks up the mechanical part right away. The relay makes the handoff feel like passing work to a colleague at the next desk rather than filing a request.

Overnight and out-of-hours runs

A relay running on a machine that stays on means work left at the end of your day is picked up when you leave it, not when someone next opens a laptop. Distributed teams use this to hand work across time zones.

Several agents, each on its own work

Each connected agent has its own token and its own stream, and only ever sees events for the tasks it created or was mentioned on. So you can run one agent per project, or one per specialism, without them tripping over each other. Run a relay per agent.

Where it does not help

If your agent’s work takes hours anyway, or if nobody is waiting on the answer, the poll is fine and the relay is one more thing to keep running. It earns its place when a person is sitting there waiting.

Run with agent, without a public URL

Selecting Run with <agent> on a task used to require the agent to have a public HTTPS address for Onplana to call, which ruled out any agent running on a laptop.

A relay counts. Your agent is always listed under Run on in the task’s agent panel; while the relay is running it is reachable, so it is selectable and the request delivers in seconds. Stop the relay and it shows as not connected with the button disabled, because there is nowhere left to deliver to. See Request an external agent run.

When the connection drops

Networks drop and laptops sleep. The relay handles this without losing your comments:

• It reconnects on its own, waiting a moment first, and staggered so that many relays reconnecting after a deployment do not arrive at once.
• It asks for what it missed. On reconnect it tells Onplana the last event it saw, and Onplana replays anything since. A brief drop costs nothing.
• If it was away too long, Onplana says so rather than pretending, and the agent falls back to a single poll to catch up.
• If your token is revoked, the relay stops instead of retrying against a connection that no longer exists.

And underneath all of it, the poll still runs. If the relay is stopped, crashed, or never installed, your agent still sees your comments on its normal schedule. Nothing is lost, it just arrives later.

FAQs

Do I need to open a port or configure my firewall? No. The relay makes an outbound connection, like a browser does. It works from a laptop, a home network, or a corporate VPN without any inbound access.

Does it cost AI tokens to run? No. The relay only carries notifications. Tokens are consumed when your agent decides to do something in response, exactly as they would be if it had found the same comment by polling.

Can I run more than one? Yes, one per connected agent. Running two relays on the same token is also safe: the newest connection takes over.

What does it see? Only events for its own agent connection: comments on tasks that agent created, mentions of that agent, and run requests aimed at it. It cannot read your projects. Anything your agent goes on to read, it reads through the normal MCP tools under its existing permissions.

Does the relay do the work? No. It delivers a notification and stops there. Whether to act, and what to do, is entirely your agent’s decision. It can ignore an event completely.

My agent is not reacting. Where do I look? Check the relay is still running and printing. If it never connected, confirm the agent made one call first (step 2) and that the URL is the API host. If it is receiving events but your agent is idle, the gap is between the relay and your agent, so check the inbox folder and the instruction telling your agent to watch it.

Is it required for the ChatGPT or Claude directory connectors? No. Those connect from the provider’s own infrastructure and do not need anything running on your machine.

Related

• Connect an external AI agent (MCP), do this first
• Request an external agent run, the button the relay enables
• Talk to an agent in a task thread, the conversation the relay speeds up
• Review and approve agent output, what happens after the agent responds
• Install the Onplana agent skills, give your agent a working routine