# Send Better Chat Compaction + WebUI to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "compaction-ui-enhancements", "name": "Better Chat Compaction + WebUI", "source": "tencent", "type": "skill", "category": "通讯协作", "sourceUrl": "https://clawhub.ai/maverick-software/compaction-ui-enhancements", "canonicalUrl": "https://clawhub.ai/maverick-software/compaction-ui-enhancements", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/compaction-ui-enhancements", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=compaction-ui-enhancements", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SKILL.md", "references/auto-compaction.ts", "references/chat-filters.diff.md", "references/compact-summary-injection.ts", "references/compaction-rpc.ts", "references/compaction-settings-view.ts" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-23T16:43:11.935Z", "expiresAt": "2026-04-30T16:43:11.935Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard", "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/compaction-ui-enhancements" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/compaction-ui-enhancements", "downloadUrl": "https://openagent3.xyz/downloads/compaction-ui-enhancements", "agentUrl": "https://openagent3.xyz/skills/compaction-ui-enhancements/agent", "manifestUrl": "https://openagent3.xyz/skills/compaction-ui-enhancements/agent.json", "briefUrl": "https://openagent3.xyz/skills/compaction-ui-enhancements/agent.md" } } ``` ## Documentation ### Compaction UI v2.1.0 Memory compaction system for the OpenClaw Control UI — background execution with toast notifications, auto-trigger at configurable token thresholds, conversation summary paragraphs in compacted output, dedicated settings tab with model selector, and result history. ### Status: ✅ Active ComponentStatusContext Gauge Button✅ WorkingBackground Compaction (toast)✅ WorkingAuto-Compaction Trigger✅ WorkingConversation Summary Paragraph✅ WorkingSettings Tab (plugin-registered)✅ WorkingModel Selector✅ WorkingLast Result Storage + Viewer✅ WorkingSettings Persistence & Reload✅ WorkingAuth Hierarchy (OAuth > API > Fallback)✅ WorkingChat History Filters✅ WorkingFull Background Isolation (no chat interference)✅ Working ### 1. Context Gauge Button (app-render.helpers.ts) A circular SVG progress ring in the chat toolbar that doubles as the manual compact trigger. Placement: After session selector dropdown in renderChatControls() Data source: sessionsResult.sessions[].totalTokens and contextTokens from session rows Colors: Green (<60%), Yellow (60-85%), Red (≥85%) Disabled: When utilization <20% or during active compaction Tooltip: Shows "Context: XK / YK tokens (Z%)" ### 2. Background Compaction (Toast) On click (or auto-trigger), compaction runs in the background using the standard bottom-right toast system — no blocking modal. The UI remains fully interactive. Running toast: Shows "Memory Compaction" with spinner Complete toast: Shows "Compacted: XK → YK" with checkmark (auto-dismisses after 5s) Error toast: Shows failure message (auto-dismisses after 5s) Uses backgroundJobToasts system consistent with all other background processes (cron, knowledge extraction, etc.) ### 3. Auto-Compaction After every chat response (final event), the UI checks token usage against the configured threshold. If exceeded: Background compaction triggers automatically Toast shows "Auto-Compacting (X%)" with the current utilization 5-minute debounce prevents repeated triggers Chat refreshes automatically after successful compaction Silent toast removal if nothing was compacted ### 4. Conversation Summary Paragraph Every compaction output now begins with a ## Conversation Summary section before the structured ## Goal section. This is a 3-6 sentence natural language paragraph that: Describes the overall topic(s) of the conversation Explains the flow of discussion and key transitions Summarizes how the conversation progressed Written in past tense as a narrative overview Implementation: Custom instructions are injected into the upstream compaction LLM call via compact.ts. The instruction is prepended to any user-provided custom instructions (from /compact [instructions]), so both coexist. Example output: ## Conversation Summary The conversation began with the user requesting improvements to the compaction system, specifically moving from a blocking modal to background toasts. Discussion then shifted to adding a settings tab with auto-compaction controls. After implementing and testing those features, the user noticed settings weren't persisting across tab navigations, which led to a fix for the module-level state cache. Finally, the user requested adding a narrative summary paragraph to the compaction output for better context. ## Goal ... ### 5. Settings Tab (Plugin-Registered) A dedicated Compaction tab under the Agent navigation group, registered via the Plugin UI architecture. Registration: plugins-ui.ts → BUILTIN_UI_VIEWS with id: "compaction", group: "agent", position: 7, icon: "archive" Cards: Auto-Compaction Card Toggle: Enable/disable automatic compaction Threshold slider: 10% to 95% (default: 60%) Color-coded: Green (<60%), Yellow (60-85%), Red (≥85%) Model Card Dropdown: Select a specific model for compaction or use session default Grouped by provider with context window sizes shown Warning callout when custom model selected (API key reminder) Fallback: If custom model fails, automatically falls back to session default Result Storage Card Toggle: Opt-in to save the compacted summary text for review Last Compaction Card Before/After: Large styled token counts in a 2-column grid Stats: Tokens saved, percent reduction, trigger type, timestamp, session key View Results: Expandable summary viewer (when storage is enabled) Clear: Reset stored result Hint: Shows "Enable Store Results" message when storage is off State Management: Module-level state persists across re-renders within a session Settings reload from backend every time the tab is visited (2-second staleness threshold) resetCompactionSettingsState() exported for tests and tab switches ### 6. Auth Hierarchy Compaction uses resolveApiKeyForProvider via getApiKeyForModel — the same auth chain as chat: OAuth → API Key → Fallback No separate configuration needed. If OAuth (Claude Max) is configured as the primary auth profile, compaction uses it automatically. Custom model selection uses this same auth chain independently. ### 7. Result Storage When enabled, the most recent compaction result is persisted to {agentDir}/compaction-config.json: { "settings": { "autoEnabled": true, "autoThresholdPercent": 60, "storeLastResult": true, "compactionModel": "anthropic/claude-sonnet-4-6" }, "lastResult": { "timestamp": 1709283600000, "trigger": "manual", "tokensBefore": 50614, "tokensAfter": 4766, "tokensSaved": 45848, "percentReduction": 91, "sessionKey": "agent:main:main", "summary": "## Conversation Summary\\nThe conversation focused on...\\n\\n## Goal\\n..." } } When storage is disabled, metadata (timestamps, token counts) is still saved but the summary text is omitted. ### 8. Chat History Filters NO_REPLY/HEARTBEAT_OK filtering: Skips assistant messages with these exact texts Compaction divider: Renders labeled divider line for __openclaw.kind === "compaction" messages ### Backend RPCs MethodDescriptionsessions.compactExecute compaction (records result after completion)compaction.getSettingsRead settings from config filecompaction.saveSettingsUpdate settings (threshold auto-clamped 10-95%)compaction.getLastResultGet stored last compaction resultcompaction.clearLastResultClear stored result ### Files Modified FilePurposesrc/gateway/server-methods/compaction.tsSettings RPCs, config I/O, result recordingsrc/gateway/server-methods/sessions.tssessions.compact RPC (records result after compaction)src/gateway/server-methods/plugins-ui.tsPlugin view registrationsrc/gateway/server-methods.tsHandler wiringsrc/gateway/server-methods-list.tsMethod registrationsrc/gateway/method-scopes.tsScope registrationsrc/agents/pi-embedded-runner/compact.tsChat summary instruction injectionui/src/ui/app-render.helpers.tsContext gauge + background toast triggerui/src/ui/app-gateway.tsAuto-compaction check after final eventui/src/ui/views/compaction-settings.tsSettings tab viewui/src/ui/app-render.tsView wiring + importui/src/ui/views/chat.tsChat history filters ### Config File {agentDir}/compaction-config.json — per-agent, created on first settings save. ### Plugin Registration The compaction tab is registered as a builtin plugin view in plugins-ui.ts: { id: "compaction", label: "Compaction", subtitle: "Memory Management", icon: "archive", group: "agent", position: 7, pluginId: "compaction-ui", } ### Known Gotchas Settings not persisting across tab visits: Fixed in v2.1.0. The module-level _state.loaded flag was preventing reloads. Now reloads every 2 seconds when re-entering the tab. Model selector requires API keys: If you select a custom model, make sure the provider's API key is configured. The UI shows a warning callout. Compaction model format: Must be "provider/model" format (e.g. "anthropic/claude-sonnet-4-6"). Invalid formats are silently ignored and fall back to session default. parentId skip-set propagation must be message-only: When filtering memory flush messages from readSessionMessages, the skip set must ONLY propagate through entries with a message field. Non-message protocol entries (type:"custom") bridge between logical turns — if their IDs enter the skip set, the entire remaining conversation gets hidden. The fix: only check parsed?.message entries against the skip set, and only add their IDs to it. No blocking modal — ever: The gauge button in app-render.helpers.ts must NEVER render a full-screen overlay modal. Compaction is a background process; all status is communicated via the bottom-right toast system. Remove any position:fixed; inset:0 overlay conditioned on compactState.phase. The button may show a spinner icon while running, but must not block the UI. ### v2.1.0 Conversation summary paragraph: Compaction output now starts with a ## Conversation Summary narrative paragraph before structured sections Model selector: Choose a specific model for compaction or use session default, with provider-grouped dropdown Settings reload fix: Tab now reloads settings from backend every 2s instead of caching forever Reference files updated: Synced references/ with current source ### v2.0.0 Background compaction: Replaced blocking full-screen modal with background job toast Auto-compaction: Triggers after chat response when token usage exceeds threshold (configurable, default 60%, 5-minute debounce) Settings tab: Plugin-registered Compaction tab under Agent nav group Result recording: sessions.compact records before/after token counts and optional summary Auth hierarchy: Same OAuth → API → Fallback chain as chat Settings RPCs: compaction.getSettings, compaction.saveSettings, compaction.getLastResult, compaction.clearLastResult ### v1.0.0 Initial release: Context gauge button, blocking modal with animated phases, sessions.compact RPC with LLM summarization, chat history NO_REPLY/HEARTBEAT_OK filtering, compaction divider lines ## Trust - Source: tencent - Verification: Indexed source record - Publisher: maverick-software - Version: 2.3.0 ## Source health - Status: healthy - Source download looks usable. - Yavira can redirect you to the upstream package for this source. - Health scope: source - Reason: direct_download_ok - Checked at: 2026-04-23T16:43:11.935Z - Expires at: 2026-04-30T16:43:11.935Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/compaction-ui-enhancements) - [Send to Agent page](https://openagent3.xyz/skills/compaction-ui-enhancements/agent) - [JSON manifest](https://openagent3.xyz/skills/compaction-ui-enhancements/agent.json) - [Markdown brief](https://openagent3.xyz/skills/compaction-ui-enhancements/agent.md) - [Download page](https://openagent3.xyz/downloads/compaction-ui-enhancements)