opencode-clm 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 From 0.1.1 on, release notes are generated by git-cliff from Conventional Commits and
 published on [GitHub Releases](https://github.com/bcmyguest/opencode-clm/releases).
 
-## 0.1.0 (unreleased)
+## 0.1.0
 
 First release: Context Language Model mode for OpenCode 1.18, ported from pi-clm 1.0.0.
 

package/README.md

@@ -1,37 +1,39 @@
 # opencode-clm
 
+[![npm](https://img.shields.io/npm/v/opencode-clm)](https://www.npmjs.com/package/opencode-clm)
+[![CI](https://github.com/bcmyguest/opencode-clm/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bcmyguest/opencode-clm/actions/workflows/ci.yml)
+
 ```
   ____ _     __  __
  / ___| |   |  \/  |
 | |   | |   | |\/| |
 | |___| |___| |  | |
- \____|_____|_|  |_|     opencode-clm: the model manages its own context in OpenCode
+ \____|_____|_|  |_|
+
+opencode-clm
+the agent that manages its own context
 ```
 
-`opencode-clm` is an [OpenCode](https://opencode.ai) plugin that runs a model as a Context
-Language Model. Before each request the plugin writes the conversation to a text file; the
-model edits that file with its ordinary tools, and the edited text is what it receives on
-the next request. OpenCode's stored session stays unchanged. It ports
-[pi-clm](https://github.com/lolipopshock/pi-clm) 1.0.0, the Pi extension that accompanies
-the paper [Context Language Models](https://arxiv.org/abs/2609.37725).
-[PORTING.md](PORTING.md) maps each pi-clm file to its counterpart here.
+`opencode-clm` is an [OpenCode](https://opencode.ai) plugin that lets the agent manage its
+own context: before each request the plugin writes the conversation to a file, the
+language model edits that file with its ordinary tools, and the edited version becomes its
+next input. OpenCode's stored session stays unchanged. It ports
+[pi-clm](https://github.com/lolipopshock/pi-clm), the Pi extension for the paper
+[Context Language Models](https://arxiv.org/pdf/2609.37725) and its [research
+codebase](https://github.com/facebookresearch/context-language-models).
 
 ## Install
 
-Tested with OpenCode 1.18.34. The package holds two plugins, and OpenCode loads them from
-two lists:
-
-- the **server plugin** (`index.ts`) in `plugin` of `opencode.json`: the mirror, edits,
-  budget, tools, and the `/clm` and `/clm-compact` commands;
-- the **TUI plugin** (`tui.ts`) in `plugin` of `tui.json`: the `/clm` panel.
-
 ```sh
-opencode plugin opencode-clm        # project: adds it to .opencode/opencode.json and .opencode/tui.json
+opencode plugin opencode-clm        # this project: .opencode/opencode.json and .opencode/tui.json
 opencode plugin -g opencode-clm     # global: opencode.json(c) and tui.json in ~/.config/opencode
 ```
 
-`opencode plugin` detects both targets from the package and writes the spec to both
-files. To do it by hand, add `"opencode-clm"` to both lists:
+The package holds two plugins: the server plugin (`index.ts`: mirror, edits, budget,
+`/clm`, `/clm-compact`) and the TUI plugin (`tui.ts`: the `/clm` panel). Install both:
+without the TUI plugin there is no panel, and each `/clm` command costs a model turn.
+`opencode plugin` writes the spec to both files. By hand, add it to both `plugin` lists;
+options go on the `opencode.json` entry only, and the TUI plugin reads them from there:
 
 ```jsonc
 // opencode.json
@@ -40,40 +42,72 @@ files. To do it by hand, add `"opencode-clm"` to both lists:
 { "plugin": ["opencode-clm"] }
 ```
 
-Options go on the `opencode.json` entry only; the TUI plugin finds that entry and reads
-the same options (`mirrorDir` above all). It recognises `opencode-clm`,
-`opencode-clm@<version or source>` (including the `opencode-clm@file:…` form `opencode
-plugin` writes for a tarball), and `file://` URLs or paths that name this package or its
-`index.ts`. From a local clone, use `file:///path/to/opencode-clm/index.ts` in
-`opencode.json` and `file:///path/to/opencode-clm/tui.ts` in `tui.json`.
-
-With the TUI plugin, a typed `/clm …` line runs in the TUI and costs no model turn: the
-panel opens, or a toast answers, or the setting changes. Only `/clm reset` goes to the
-server command. Without the TUI plugin (or with `opencode run --command clm`), the server
-command answers `/clm` as text, which costs one model turn because OpenCode cannot cancel
-a command. Version 0.1.0 on npm has the server plugin only; the panel and `/clm config`
-arrive with 0.2.0.
-
 ## Quick start
 
 | command | what it does |
 |---------|--------------|
-| `/clm` | open the panel: **overview** (context size per request, fixed overhead and usable budget, every accepted edit) <br><img src=".github/images/overview.png" alt="The overview page: context size per request, with the requests after which the model edited its context" width="720"> <br> **input** (what the next request will contain) · **edits** (each revision, message by message, with a side-by-side diff) <br><img src=".github/images/edits.png" alt="The edits page: a tool result before and after the model shortened it" width="720"> |
-| `/clm status` | a toast: CLM on or off, revision, last request size, budget, fixed overhead, last outcome (the server command's text adds the changed settings) |
-| `/clm config` | open **settings**; `/clm config <setting> <value>` changes one, `/clm config reset` drops this session's changes <br><img src=".github/images/settings.png" alt="The settings page: sizes, files, and every setting" width="720"> |
-| `/clm-compact [instructions]` | ask the model to compact its context now; text you add (what to keep, for example) goes into the prompt. The result shows on the **edits** page |
-| `/clm on` / `off` / `reset` | apply edits or send the raw history for this session (the `editing` setting); `reset` drops the accepted revision (server command, one model turn) |
-
-In the panel: `1–4` or `Tab` switch pages, `← →` step through the overview's list
-(edits, rejections, resets, compactions, now) or the edits page's revisions, `z` zooms
-the chart, `Enter` opens the selection, `r` reloads, `q` closes.
+| `/clm` | open the panel: **overview** (context size per request + every accepted edit) <br><img src="https://raw.githubusercontent.com/bcmyguest/opencode-clm/main/.github/images/overview.png" alt="The overview page: context size per request, with the requests after which the model edited its context" width="720"> <br> **input** (what the next request contains) · **edits** (per-revision side-by-side diff) <br><img src="https://raw.githubusercontent.com/bcmyguest/opencode-clm/main/.github/images/edits.png" alt="The edits page: a tool result before and after the model shortened it" width="720"> |
+| `/clm overview` / `input` / `edits` / `settings` | open the panel on that page (`timeline` and `edit` also work); without the TUI plugin, print it as text |
+| `/clm status` | a toast: on or off, revision, last request size, budget, fixed overhead, last outcome; `mode notices-only` when set |
+| `/clm config` | open **settings**; `/clm config <setting> <value>` changes one, `/clm config reset` drops this session's changes <br><img src="https://raw.githubusercontent.com/bcmyguest/opencode-clm/main/.github/images/settings.png" alt="The settings page: sizes, files, and every setting" width="720"> |
+| `/clm-compact [instructions]` | ask the model to compact its own context now; anything you add (e.g. what to keep) is passed along. The result shows on the **edits** page |
+| `/clm on` / `off` / `reset` / `path` | enable, use raw context, discard the accepted revision, show the mirror's path |
+| `/clm budget [value]` | show or change the budget, the same as `/clm config budget`: a share of the model window (default `50%`), tokens (`64k`), or `window` |
+| `/clm config mode notices-only` | keep the budget notices, reminders and overflow guard but take away editing: no mirror, no protocol prompt, raw history. For comparing "telling the model its budget" with "letting it edit"; `/clm config mode edit` switches back |
+
+With the TUI plugin, typed `/clm …` lines run in the TUI and cost no model turn, and Tab
+completes their subcommands, setting names and values;
+`/clm reset` is handed to the server plugin, also without a turn. The right of the
+session prompt shows `clm <size> / <budget> · r<revision>` (`~` before the size marks an
+estimate the provider has not confirmed; `clm off · r<revision>` while CLM is off;
+`clm notices-only <size> / <budget> · r<revision>` in notices-only mode).
+
+In the panel: `1–4` or `Tab` switch pages, `← →` step through the overview's markers or
+the edits page's revisions, `z` zooms the chart, `Enter` opens the selection, `r`
+reloads, `q` closes.
+
+## Benchmarks
+
+These numbers come from one machine (AMD Strix Halo, gfx1151, Vulkan) running
+Qwen3.8-Flash-Next (UD-IQ4_XS) through lemonade, on a llama.cpp build with an
+unreleased patch that ports the paper's
+[Suffix Cache Reuse](https://github.com/facebookresearch/context-language-models/tree/main/suffix_cache_reuse)
+(an SGLang patch) to llama.cpp's hybrid models. On a stock server, an edit re-prefills
+everything after the first changed token.
+
+**GSM8K, 50 test problems, edited prompt.** Each problem is primed with an 8-shot prompt
+holding three stale worked examples, then asked again with that block replaced by a
+one-line note, mirroring a CLM edit. Temperature 0, thinking off.
+
+| | reuse after the edit | full prefill |
+|---|---|---|
+| accuracy | 48/50 | 49/50 |
+| median tokens prefilled | 23 | 1,362 |
+| median prompt time | 0.51 s | 5.02 s |
+| median request time | 3.1 s | 7.2 s |
+
+**A live OpenCode session** with opencode-clm 0.2.0 (48k budget, auto-compaction off)
+read and summarised every file under `src/` and `test/` of this repository and wrote its
+notes: 49 requests, 16 accepted edits, 0 rejected. The server reused cache after 23 edits
+and prefilled 11,240 tokens in total, where a prefix-only cache would have prefilled
+214,585 (95% less); requests of 20–48k tokens prefilled 34–3,523 tokens each.
+
+**Nine agent tasks in OpenCode** (find and fix, opencode-clm 0.3.0, 1 run each), CLM
+at a 32k budget vs CLM off: both solved 9/9; CLM took 55.5 s per task vs 91.3 s and
+prefilled 2,868 tokens vs 7,317 on average. CLM accepted only 1 edit in 9 runs because no
+task came near the budget, so most of the gain looks behavioural: told its budget, the
+model makes fewer tool calls. One CLM run read files outside its workspace and is not
+comparable.
+
+Flash-Next was not trained for CLM, so it makes more edit mistakes than the paper's
+trained models. Hosted APIs are untested.
 
 ## Docs
 
-- [How it works](docs/how-it-works.md): the mirror, edits, the budget, compaction, the panel, safety.
-- [Configuration](docs/configuration.md): sizing the budget, every setting and its environment variable, `/clm config`.
-- [Architecture](docs/architecture.md): modules, session files, design notes, known limitations.
-- [Development](docs/development.md): setup, checks, the integration suites, releasing.
+- [How it works](docs/how-it-works.md) — the mirror, what runs without the model, the panel, model and server support, safety.
+- [Configuration](docs/configuration.md) — every setting (editing, budget, reserve, reminders, reminder-cooldown, gate, guard, compaction, cap, steering, mode, one-tool, trailer, compact-prompt, reasoning), plugin options and environment variables.
+- [Architecture](docs/architecture.md) — modules, session files, design notes, known limitations.
+- [Development](docs/development.md) — setup, checks, the integration suites, releasing.
 
 ## Citation
 
@@ -94,27 +128,14 @@ If you use opencode-clm in your research, please cite
 ## Credits
 
 - [pi-clm](https://github.com/lolipopshock/pi-clm) 1.0.0 (MIT, Copyright 2026 Emanuel
-  Casco): the design and most of the code derive from it, the `/clm` panel included
-  (`src/panel/timeline.ts`, `src/panel/diff.ts` and the page layouts in
-  `src/panel/view.ts` port its `timeline.ts`, `diff.ts` and `viewer.ts`). Model-facing text
-  taken from pi-clm, adapted: the compaction prompt (`src/compact.ts`), the `clm-context`
-  skill, the budget notices, the mirror rejection and receipt messages, and the overflow
-  and observation notes. `steering/house-brief.md` is byte-identical to pi-clm's. Written
-  for this package: the system-prompt protocol section (`src/presentation.ts`), the
-  edit-gate refusal note, and the plugin's own receipts, commands and tool descriptions.
-  [NOTICE](NOTICE) lists the files; [LICENSE](LICENSE) carries pi-clm's notice.
-- Context Language Models, [arXiv 2609.37725](https://arxiv.org/abs/2609.37725), and
-  [facebookresearch/context-language-models](https://github.com/facebookresearch/context-language-models)
-  (CC BY-NC 4.0). This package copies no text from that repository (normalized 5-gram
-  check: no shared span over 6 tokens). The `fit` / `shrink` edit gate and the default
-  25/50/75% reminder steps follow its harness design, and the edit-cost advice in the
-  skill, inherited from pi-clm, covers the same points as the harness prompt in different
-  words. This package is not licensed under CC BY-NC and is not endorsed by its authors.
-
-## AI assistance
-
-Claude Code (Claude Opus) wrote the code and documentation in this repository. The
-maintainer has not hand-reviewed them.
+  Casco): the design and most of the code derive from it, the `/clm` panel included, and
+  most model-facing text is adapted from it. [NOTICE](NOTICE) lists the files.
+- [facebookresearch/context-language-models](https://github.com/facebookresearch/context-language-models)
+  (CC BY-NC 4.0): this package copies no text from it; the `fit` / `shrink` edit gate and
+  the default 25/50/75% reminder steps follow its harness design. This package is not
+  licensed under CC BY-NC and is not endorsed by its authors.
+- Claude Code (Claude Opus) wrote the code and documentation; the maintainer has not
+  hand-reviewed them.
 
 ## License