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:
| Part | For example |
|---|---|
| What it does | Draft the reply to your accountant |
| Why now | Your accountant wrote two hours ago |
| What it will do | Reads the thread and drafts a reply. Sends nothing |
| What it may touch | Drafts the email and sends nothing |
| How long | ~15m |
| When it presses | due 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:
/heartbeatIt 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.
| Command | Does |
|---|---|
/heartbeat | Makes this session the heartbeat, looking every 55 minutes |
/heartbeat 15m, /heartbeat 2h | The same, on another interval |
/heartbeat now | Looks right away |
/heartbeat status | Whether this session is the heartbeat, its interval, when another session in the home was last active, and how many proposals show |
/heartbeat off | Stops 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 when | Otherwise |
|---|---|
| The session is idle | It 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
| Choice | What happens |
|---|---|
| Start | A fresh session opens and runs the proposal. In cmux, it opens as a tab beside the heartbeat |
| Later | It goes away until 08:00 |
| Skip | It'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.
Attention
Plan your day and keep it in view. Today's three, what slipped, the week and month, the roadmap in flight, who is waiting on you, your standup, and a checklist of where every session stands.
Standup and checkpoints
Where things stand, at a glance. Your standup as a card to read while you talk, and a checklist of where one session, or every recent session, has got to.