smart-compaction

dsh plugin --profile web add smart-compaction

<p align="center">

<img src="https://raw.githubusercontent.com/JoblessJoe/smart-compaction/main/.github/assets/banner.svg?v=2" alt="smart-compaction: dsh auto-compacts mid-task; with smart-compaction the model compacts between tasks" width="100%">

</p>

<p align="center">

<a href="https://www.npmjs.com/package/smart-compaction"><img src="https://img.shields.io/npm/v/smart-compaction?color=a78bfa&label=npm" alt="npm version"></a>

<a href="https://www.npmjs.com/package/smart-compaction"><img src="https://img.shields.io/npm/dm/smart-compaction?color=a78bfa" alt="npm downloads"></a>

<a href="LICENSE"><img src="https://img.shields.io/github/license/JoblessJoe/smart-compaction?color=a78bfa" alt="MIT license"></a>

<a href="https://joblessjoe.com/smart-compaction"><img src="https://img.shields.io/badge/website-joblessjoe.com-a78bfa" alt="project page on joblessjoe.com"></a>

<a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://img.shields.io/badge/awesome-dsh--plugin-fc60a8" alt="listed on awesome-dsh-plugin"></a>

</p>

A DeepSeek Harness (dsh) plugin that lets the model decide when to compact its own context, instead of being cut off mid-task by a blind token threshold.

• compact_now: compacts at a point the model knows is safe, e.g. right after finishing a todo. Works mid-turn.
• context_status: real token usage against the session's actual context window, so the model stops guessing.
• Automatic safe-point compaction: local models rarely call a tool like this on their own, so the plugin also compacts by itself the moment a todo item is marked done and the context is over half full. No model decision needed.
• No config, no core changes: built only on dsh's public compaction APIs.

npx @deepseek-ai/dsh plugin --profile web add smart-compaction

The web profile reloads live, so there's nothing to restart. Details and edge cases under [Install](#install).

Why

dsh's built-in compaction is purely reactive: an automatic trigger fires between agent steps

whenever token pressure crosses a fixed threshold, with no idea whether that moment is a good one

to interrupt. It can land between two dependent steps — e.g. right after reading a file and right

before editing it based on what was just read — and the resulting summary loses exactly the

context the very next step needed.

This plugin doesn't change how compaction works, only who decides when. It hands the model a

tool it can call proactively, on its own judgment, instead of leaving that decision entirely to a

blind token counter.

What it does

Two tools, both no-argument.

compact_now

• Selects the largest currently-compactable span of conversation history — the same

tool-call-pairing-safe boundary logic dsh's own compaction already guarantees, reimplemented

here against dsh's public APIs only (no dsh core changes, no dependency on

compaction-basic's internals).

• Posts a one-line "Compacting now" notice to the chat before calling compactRegion(), not

after — the summarization call is one extra model request and can take a while (minutes, on a

local model), and without this the chat just looks stuck between the tool call and its result.

Tagged with its own source kind and form: 'notice' (the same tagging dsh-compaction-basic's own

checkpoint messages and other host-generated asides use), so it renders as a collapsed system aside, not as

if the user typed it, and needs no model output of its own.

• Calls dsh's own ctx.compaction.compactRegion() to actually do the compaction — the same

summarizer, the same durable compaction/start/compaction/end log events, the same guarantees

as any other compaction in the session.

• No-ops harmlessly ("Not enough compactable history yet.") if there isn't enough history yet —

safe for the model to call speculatively. No notice is posted for a no-op call.

context_status

• Read-only — never modifies the session, safe to call anytime.
• Reports current token usage and the model's actual context-window size for this session,

e.g. "~42,300 / 77,824 tokens used (54.3%)."

• Reads dsh's own contextPressure session projection (registered by

@deepseek-ai/dsh-token-meter, mounted wherever compaction-basic is) via the public

ctx.sessionProjections.stateOf() API — the same numbers the web UI's own context meter

reads. Nothing is hardcoded: the context-window figure comes from whatever model this

session is actually routed to, so it's correct unchanged across different models, profiles,

and context-window sizes.

• Exists because, without it, the model has zero visibility into its own context usage — the

only prior signal was a vague "if the conversation feels long" in compact_now's own

description.

Automatic safe-point compaction

• Watches todo_write. When an item flips to completed, that's a finished step: a safe place

to cut.

• If usage is past safePointRatio (default 0.5) at that moment, the next step starts on

compacted history. Same notice, same compactRegion() path as compact_now.

• dsh's own 80% trigger stays as the backstop; this just gets there first, at a clean boundary.
• A failure here never breaks the turn. It logs a warning and the backstop takes over.
• Tune or turn it off in your profile's cordis.patch.yml:

  - id: tool-compact-now
    config:
      safePointRatio: 0.6   # or false to disable

How it works

Two entry points exist on dsh's compaction service: compactNow() (what the human /compact

command uses — requires an idle agent, throws busy otherwise) and compactRegion() (what

dsh's own automatic between-step trigger uses — works fine mid-turn). A tool's execute()

always runs mid-turn — that's what calling a tool means — so compact_now is built on

compactRegion(), not compactNow().

Install

Into your dsh **web

…(truncated)