AgentLayer▸docs
Use it

Proposals

Sessions the agent lines up for you to start. One long-running session, the heartbeat, keeps the best five waiting, and you choose Start, Later or Skip.

In short

A proposal is a session the agent has prepared and waits on your yes for. Start a heartbeat once, in a session you leave open in the home, and it keeps the best five proposals waiting. Start one and a fresh session runs it; Later brings it back in the morning; Skip drops it.

The agent often knows the next thing worth doing before you ask: a task due this week, a sync that's overdue, a review waiting on you. Proposals put each one in front of you as a ready-to-run session, so starting it is one tap and ignoring it costs nothing.

A proposal

Each proposal says what the session will do and where it stops, before anything runs:

PartFor example
What it doesDraft the reply to your accountant
Why nowYour accountant wrote two hours ago
What it will doReads the thread and drafts a reply. Sends nothing
What it may touchDrafts the email and sends nothing
How long~15m
When it pressesdue Sat, when it does

Proposals are written as drafts only: each one's prompt tells its session not to send, post, pay, merge or delete, and anything on your home's ask-first list still asks.

Start a heartbeat

In a session you'll leave open in the home, run:

/heartbeat

It looks for proposals at once, at any hour, then every 55 minutes. In cmux, the Manager's PROPOSED section has a Start heartbeat card for every agent without one, which opens that session for you.

CommandDoes
/heartbeatMakes this session the heartbeat, looking every 55 minutes
/heartbeat 15m, /heartbeat 2hThe same, on another interval
/heartbeat nowLooks right away; in the heartbeat's own session, refreshes the brain first when one is due
/heartbeat statusWhether this session is the heartbeat, its interval, when another session in the home was last active, and how many proposals show
/heartbeat offStops it

Setting, stopping and checking the heartbeat take no model turn; each look (at once on /heartbeat, or with /heartbeat now) is one. See Mods.

A home has one heartbeat. Running /heartbeat in a second session moves it there, and both sessions say so. The heartbeat stays with its session across /clear and /resume; closing the session (/exit, or closing its tab) gives it up.

What the heartbeat shows

In Claude Code, the heartbeat's session keeps a band above its prompt, so a glance at its tab says what it's doing and what it did:

💓 Heartbeat ○ next look in 23m · 09:55
   every 55m · 5 of 5 proposals showing · brain refreshed 2h ago
   09:00 ✓ Proposed 2, retired 1: Draft the reply to your accountant; Run the full sync.
   08:05 – skipped 3× since 06:20 · home idle

The first line is what it's doing now: looking for proposals, refreshing the brain, or counting down to the next look, yellow once a look is overdue (as when your Mac slept through it). Under it, the interval, how many proposals show, and how long ago the brain was refreshed. Then its last three looks and skips, newest first:

MarkMeans
✓A look that proposed or retired something
·A look that found nothing new
↻A brain refresh
–A skipped wake, and why; repeats fold into one line
✗A look or refresh that was stopped

After each look or refresh, the dashboard and the cmux sidebar update on their own.

When it looks

A wake spends a model turn, so the heartbeat only wakes when there's a reason to:

It wakes whenOtherwise
The session is idleIt waits for the current turn to end
Another session in the home was active within the interval (syncs and agent-run sessions count)It skips the wake, and wakes on the next tick after one is

A full list doesn't stop it: five proposals showing is what it keeps up, not a reason to rest. Every six hours, when a session has written in the home since the last sync or refresh, the wake starts with a brain refresh. The day's first wake, and every refresh, clears the session first, so the heartbeat never grows a long conversation.

Each look gathers, in order, from your tasks (overdue and due-this-week P0 and P1 work first, then the next step of an active P1 task), the brain (a full sync three or more days old, whose questions wait for you, and tasks a refresh just found stalled), GitHub when the GitHub pack is on (a review asked of you, a comment on your pull request, red CI on your branch), and every proposal source. It leaves out work a session in the home took up in the last six hours. It also rewrites the board's summary once it's six hours old.

Then it keeps the best five: it adds the strongest candidates and retires the showing proposals they beat, or that no longer hold (a closed task, a merged pull request, work a session has taken up). A proposal is never retired for filler, and one you put off with Later is left alone. When nothing beats what's showing, it changes nothing: a quiet hour is a good hour.

Start, Later or Skip

ChoiceWhat happens
StartA fresh session opens and runs the proposal. In cmux, it opens as a focused tab in the agent's workspace that fits the work (Opening a session)
LaterIt goes away until 08:00
SkipIt's dropped

In cmux, each card has the three buttons. In Claude Code, /proposal start <id>, /proposal later <id> or /proposal skip <id> does the same. From a terminal, the CLI's proposals list and proposals decide. Where Start can't open a session for you, it prints the command to run.

Nothing comes back twice too soon: a source already waiting, started in the last day, or skipped in the last week isn't proposed again.

Your own rules

To change what gets proposed in your home (more of one kind, none of another, nothing from one project), write it in extensions/skills/proposals.md. The heartbeat reads it on every wake, and it wins where the two disagree. See Extending a plugin skill.

Proposal sources

A proposal source adds something new for the heartbeat to look at, such as a support queue or a school calendar, without changing the plugin. It is an ordinary skill with two marks:

  • its name starts proposals- (proposals-support);
  • its description starts "Proposal source:" and says what it watches.

Put it in a plugin's skills/ for everyone who installs that plugin, or in the home's .claude/skills/ for that home alone. On every wake the heartbeat runs each source it can see. A source looks with its own tools and returns at most three candidates, most pressing first, each with its source key prefixed by its own name (support:ticket-412). It never adds them itself, writes nothing and sends nothing: the heartbeat weighs every candidate together with the proposals already showing and keeps the best five.

---
name: proposals-support
description: Proposal source: tickets waiting on the operator for more than a day in the support queue.
allowed-tools: mcp__plugin_acme_support__tickets
---

# Proposal source: support

List open tickets assigned to the operator. For each waiting more than a day, oldest first, at most
three, return a candidate: source `support:ticket-<id>`, title "Draft a reply to ticket <id>",
what it will do, what it may touch (a private note only), an estimate, and the whole prompt for a
fresh session, ending "Stop and show me the draft."

Return the list and nothing else.

The full contract is in the plugin's skills/proposals/references/sources.md.

Where it's kept

The list lives in .state/proposals.json in the home, and a started proposal's prompt in .state/proposals/. The proposal_add tool is how the heartbeat adds to it.

On this page