openclaw/docs/tools/progress-card.md

summary, title, sidebarTitle, read_when

summary	title	sidebarTitle	read_when
Maintain one durable plan and status card for a session	Progress card	Progress card	You want an agent to publish durable at-a-glance progress for its current session You need the progress_card input, limits, rendering, or clearing contract

progress_card is the single agent status tool for a session. It stores an ordered step plan, a compact Markdown note, or both. Each call replaces the whole card, so the latest write is the source of truth for someone following the work without reading the transcript.

The card is durable session state. A reconnect or page reload reads the latest card from the Gateway instead of reconstructing it from tool events or transcript history. The transcript keeps only a short update receipt, not another full copy of the card.

Update a card

Both input fields are optional:

• plan: up to 50 ordered steps. Each step has non-empty step text and a status of pending, in_progress, or completed. At most one step may be in_progress.
• markdown: a compact narrative about what happened, what is blocked, or what comes next. Use it when a glanceable note says more than the step list; do not repeat the plan in Markdown.

For example:

{
  "plan": [
    { "step": "Inspect the failing route", "status": "completed" },
    { "step": "Repair the session owner", "status": "in_progress" },
    { "step": "Run focused verification", "status": "pending" }
  ],
  "markdown": "The failure is isolated to session ownership. No blocker."
}

Every call is a replacement, not a patch. Omitting markdown removes the previous note; omitting plan removes the previous checklist.

The tool returns a short receipt such as Progress card updated (rev 4, 1/3 done) or Progress card updated (rev 4) when there is no plan. Its structured result contains the revision and either completed/total step counts or null when no plan is present. OpenClaw also emits plan events for native apps and channel renderers during their migration, but the durable card remains the authoritative state.

Format the note

Markdown accepts ordinary formatting, small tables, links, and optional progress bars:

Tests are running.

<progress value="3" max="7"></progress>

| check      | state   |
| ---------- | ------- |
| unit tests | passed  |
| live flow  | running |

The Control UI renders progress elements with value and max attributes. Other raw HTML is stripped by the Markdown sanitizer.

Limits

• Markdown: at most 8,192 UTF-8 bytes.
• Plan: at most 50 steps.
• Step text: non-empty and at most 512 UTF-8 bytes per step.
• Active work: at most one in_progress step.

The Gateway removes invisible Unicode and bidirectional control characters from Markdown and step text before storing the card.

Clear a card

Call progress_card with both parts absent or empty to remove the current card:

{}

An empty plan plus empty or whitespace-only Markdown also clears it. A successful clear returns Progress card cleared.

Where the card appears

The current chat shows exactly one live card:

• When the session rail is visible, the card appears in the rail.
• At narrow widths where the rail is hidden, the card appears in the collapsible surface beside the composer.

The two placements are mutually exclusive. Other sessions can show their latest card in the sidebar hovercard. All placements read the same Gateway-backed state and refresh after progressCard.changed notifications.

Pin the card to the dashboard

Use the dashboard tool to keep the live card on the current session's dashboard:

{
  "action": "widget_put",
  "name": "session-progress",
  "title": "Session progress",
  "pluginKind": "session:progress",
  "size": "md"
}

Omit props.sessionKey to follow the dashboard's session. To show another session's card, add "props": { "sessionKey": "agent:main:release" }. The current connection must participate in that session; otherwise select an accessible session or change its sharing.