AgentLayer▸docs
Use it

Proposals

Sessions the agent lines up for you to start. One long-running session, the heartbeat, keeps up to 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 up to 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, and its reply says whether it looked or why not (the proposals are full). 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
/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.

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
Fewer than five proposals show, and fewer than 20 wait in all (put-off ones included)It skips the wake

The day's first wake clears the session first, so the heartbeat never grows a long conversation. Each wake looks, in order, at your tasks (overdue and due-this-week P0 and P1 work first, then the next step of an active P1 task), the brain (a sync three or more days old, or a compile backlog), 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 also rewrites the board's summary once it's six hours old. Then it proposes the best few, or 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 tab beside the heartbeat
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 and keeps the total at 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