Using LLM for Heartbeats?

[Yeraze]

Seems like this is a HUGE waste of tokens.. You have a handful of agents each processing the giant Paperclip prompt just to look if issues are assigned?

I get that some agents are "Special", but can we get a basic "Paperclip Built-in" heartbeat that when enabled is just a basic query to "Return the highest-priority open issue assigned to me"?

[mchosc]

We ran into the exact same problem running 49 agents. The fixed heartbeat interval means every agent wakes up on schedule, processes the full prompt, and most of them just say "no tasks" — burning tokens for nothing.

We built several things to address this:

1. Separate heartbeat model

Our OpenRouter adapter supports a heartbeatModel config — heartbeats without assigned work use a cheap/fast model (we use mistralai/mistral-small-3.2-24b-instruct) while actual task work uses the default or complex model. This alone cuts heartbeat cost dramatically since the "no tasks" response needs minimal intelligence.

2. Adapter-level skip for idle agents

Agents with no assigned issues get a minimal "routine heartbeat, no tasks" prompt instead of the full system prompt. These runs complete in 8-10 seconds with ~200 tokens. The adapter also skips cancelled/done/blocked issues immediately (0 tokens).

3. Adaptive Heartbeat plugin (repo)

Instead of optimising the heartbeat itself, we replaced the scheduling model entirely. The plugin listens to issue.created and issue.updated events and uses ctx.agents.invoke() to wake agents immediately when they have work. After a run completes, it checks remaining backlog and re-invokes after a short delay (60-120s based on queue depth).

We set the fixed heartbeat interval to 12 hours as a fallback safety net and let the plugin handle all fast scheduling. Result:

• Agents with work get invoked in seconds, not hours
• Agents without work don't run at all (no wasted tokens)
• Backlog clears 10-50x faster than fixed intervals
• Cost impact is zero or negative

The plugin needs issue.created/issue.updated events (which already fire) and the agents.invoke capability from the plugin SDK. No upstream changes required — works with current Paperclip.

The deeper fix would be what you're describing — a lightweight built-in heartbeat that just checks "do I have work?" without running the full adapter. But event-driven invocation sidesteps the problem entirely: if there's no event, there's no run.

We also submitted PR #2686 to emit agent.run.started/finished/failed/cancelled plugin events, which lets plugins like this react to run completions (e.g., re-invoke if backlog remains).

[Sterdizzy]

Interesting idea. When I tried to install this, it says that the NPM package has not been published. I tried installing local and failed as well.

[mchosc]

The plugin isn't published to npm — it's installed from a local path since it requires the OpenRouter adapter (which is also in our custom fork, not upstream yet).

To use it on your deployment:

# Clone the repo
git clone https://github.com/Animus-Systems/paperclip-plugin-adaptive-heartbeat.git
cd paperclip-plugin-adaptive-heartbeat
npm install && npm run build

# Install in Paperclip (from inside the container, adjust path to where you cloned it)
cd /path/to/paperclip/.paperclip/plugins
npm install /path/to/paperclip-plugin-adaptive-heartbeat

# Then register via UI: Settings → Plugins → Install → @animusystems/paperclip-plugin-adaptive-heartbeat

The plugin itself doesn't depend on our adapter fork — it uses standard plugin SDK capabilities (agents.invoke, issues.read, events.subscribe). It should work with any Paperclip deployment running the current plugin SDK.

The separate heartbeat model (heartbeatModel config) does require our OpenRouter adapter though. If you're using claude_local or another adapter, the adaptive scheduling part still works — it just won't have the cheap-model-for-heartbeats optimization.