From d6b6ea609ab05974269ff9429087663223738785 Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Tue, 30 Jun 2026 16:56:28 +0700 Subject: [PATCH 1/8] Add breakdown configuration doc --- docs/breakdown-configuration.md | 186 ++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/breakdown-configuration.md diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md new file mode 100644 index 00000000..1904c691 --- /dev/null +++ b/docs/breakdown-configuration.md @@ -0,0 +1,186 @@ +# Magic Context - Breakdown & Configuration + +## Installation + +### Proper Install - Global Scope (recommended) + +```bash +opencode plugin @cortexkit/opencode-magic-context --global +``` + +This: +1. Runs `npm install --ignore-scripts` into the opencode cache +2. Adds the plugin to `opencode.jsonc` `plugin[]` list +3. Registers server and tui targets + +### Package Cache Locations + +| Location | Purpose | +|----------|---------| +| `~/.cache/opencode/packages/@cortexkit/` | Proper install by `opencode plugin` | +| `~/.cache/opencode/node_modules/@cortexkit/` | Manual `npm install` (not canonical) | +| `~/.npm/_npx/` | Cached from npx (not persistent) | + +### Backend Data + +| Location | Contents | +|----------|----------| +| `~/.local/share/cortexkit/magic-context/` | SQLite DB, model limits, ONNX model, RPC sockets | +| `~/.local/share/opencode/opencode.db` | OpenCode conversation database | + +### Verify + +```bash +grep 'magic-context' ~/.config/opencode/opencode.jsonc +ls ~/.cache/opencode/packages/@cortexkit/opencode-magic-context@latest/ +ls ~/.local/share/cortexkit/magic-context/ +``` + +--- + +## Plugin Schema + +### opencode.jsonc Entry + +```jsonc +{ + "plugin": [ + "@cortexkit/opencode-magic-context" + ] +} +``` + +No `@latest` tag - `opencode plugin` resolves and strips it on install. + +### Agent Model Binding + +All agents reference `"model": "opencode/big-pickle"` (160K context). + +Available `opencode/` model IDs: +- `big-pickle` - 160,000 context +- `deepseek-v4-flash` - 1,000,000 context +- `deepseek-v4-flash-free` - 200,000 context +- `deepseek-v4-pro` - 1,000,000 context +- `claude-sonnet-4` - 1,000,000 context +- `claude-opus-4-7` - 1,000,000 context +- `gpt-5.4` - 922,000 context +- `gemini-3.5-flash` - 1,048,576 context + +### Compaction Settings + +```jsonc +{ + "compaction": { + "auto": false, + "prune": false, + "reserved": 20000 + } +} +``` + +When Magic Context is active, compaction is managed by the plugin, not OpenCode's native engine. + +--- + +## Backend Architecture + +### Data Directory: `~/.local/share/cortexkit/magic-context/` (~96 MB) + +| File | Purpose | +|------|---------| +| `context.db` (+SHM, +WAL) | SQLite - session state, compacted history | +| `model-context-limits-opencode.json` | Per-model context limits (2,400+ entries) | +| `models/Xenova/all-MiniLM-L6-v2/` | ONNX embedding model | +| `rpc/` | RPC communication ports | +| `last_announced_version` | Version announcement tracker | + +### Model Context Limits + +The `model-context-limits-opencode.json` caches context window limits populated from OpenCode's `config.providers()` SDK endpoint. Magic Context reads the live resolved config (never reads `models.json` directly) to avoid torn-read issues. + +```jsonc +{ + "opencode/big-pickle": 160000, + "opencode/deepseek-v4-flash": 1000000, + // ... 2400+ entries +} +``` + +### Context Resolution Flow + +``` +Plugin startup -> warm apiCache from last-known-good file +OpenCode SDK -> config.providers() -> merged models + (live + compiled-in + auth-plugin caps) +Magic Context -> consumes merged result +Result bounded to [20k, 3M] range +``` + +### Process Architecture + +``` +OpenCode (main process) + +-- MCP servers (git, mempalace, hf-mcp, etc.) + +-- Magic Context (child process) + +-- SQLite (context.db) + +-- ONNX model (all-MiniLM-L6-v2) + +-- RPC socket +``` + +--- + +## Troubleshooting + +### "Model not found: opencode/small-pickle. Did you mean: big-pickle?" + +**Cause:** OpenCode's runtime tries to resolve `opencode/small-pickle` which doesn't exist in the model catalog. Appears during context compaction cycles. + +**Solution:** Harmless - no functional impact. `big-pickle` (160K context) is the correct model already configured for all agents. This is an upstream model alias issue - cannot fix via config. Ignore or report to OpenCode. + +### Duplicate Plugin Entries + +**Solution:** Check both config files: + +```bash +grep 'magic-context' ~/.config/opencode/opencode.jsonc +cat ~/.opencode/opencode.json # delete if global scope used +cat ~/.opencode/tui.json # delete if global scope used +``` + +Keep plugin in only one scope. + +### Package Missing (Plugin Registered But Not Installed) + +**Symptom:** Plugin listed in config but OpenCode shows loading errors. + +**Solution:** Install manually to cache: + +```bash +cd ~/.cache/opencode && npm install @cortexkit/opencode-magic-context --ignore-scripts +``` + +Or re-install with `opencode plugin @cortexkit/opencode-magic-context --global`. + +--- + +## FAQ + +### Q: Why does Magic Context use its own SQLite database? + +The plugin needs persistent session state for context management that survives OpenCode restarts. It cannot rely on OpenCode's in-memory state. The database at `context.db` stores compacted history, configuration overrides, and session bookkeeping. + +### Q: Where does the ONNX model come from? + +`all-MiniLM-L6-v2` is a sentence-transformer embedding model downloaded from Hugging Face (Xenova/onnx conversion). It's used by Magic Context's sidebar for semantic compression features. + +### Q: Does Magic Context read `~/.cache/opencode/models.json`? + +No. Magic Context explicitly does NOT read `models.json` due to torn-read issues. It consumes the merged, live-resolved model config from OpenCode's `config.providers()` API endpoint, which already combines the live cache, compiled-in snapshot, opencode.json overrides, and auth-plugin caps. + +### Q: What happens if both local and global scope have the plugin? + +OpenCode loads both entries, potentially causing duplicate initialization. Remove one scope (preferably the local `~/.opencode/` files) to keep only the global scope. + +### Q: Is the opencode/small-pickle error breaking anything? + +No. It's a console warning during compaction with zero functional impact. The model routing still works correctly with the configured `opencode/big-pickle`. From 85383289bc1db609add8d23dd652efa699af573a Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Tue, 30 Jun 2026 18:01:20 +0700 Subject: [PATCH 2/8] =?UTF-8?q?fix:=20address=20PR=20review=20feedback=20?= =?UTF-8?q?=E2=80=94=20use=20safe=20plugin-removal=20instructions=20and=20?= =?UTF-8?q?fix=20verify=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/breakdown-configuration.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md index 1904c691..cc2b3f63 100644 --- a/docs/breakdown-configuration.md +++ b/docs/breakdown-configuration.md @@ -32,7 +32,7 @@ This: ```bash grep 'magic-context' ~/.config/opencode/opencode.jsonc -ls ~/.cache/opencode/packages/@cortexkit/opencode-magic-context@latest/ +ls ~/.cache/opencode/packages/@cortexkit/ ls ~/.local/share/cortexkit/magic-context/ ``` @@ -143,8 +143,20 @@ OpenCode (main process) ```bash grep 'magic-context' ~/.config/opencode/opencode.jsonc -cat ~/.opencode/opencode.json # delete if global scope used -cat ~/.opencode/tui.json # delete if global scope used + +# Check if local scope files exist and what's in them: +cat ~/.opencode/opencode.json 2>/dev/null +cat ~/.opencode/tui.json 2>/dev/null +``` + +**To remove only the plugin entry (not the whole file)** — if the local files contain other settings beyond the plugin entry, edit the file and remove just `"@cortexkit/opencode-magic-context"` from the `"plugin"` array. If the file contains only the plugin entry or no other useful config, delete the entire file: + +```bash +# Safe deletion check — only if file consists solely of the plugin entry: +if [ -f ~/.opencode/opencode.json ] && [ "$(jq '.plugin | length' ~/.opencode/opencode.json 2>/dev/null)" = "1" ]; then + rm ~/.opencode/opencode.json + echo "Removed (only plugin entry)" +fi ``` Keep plugin in only one scope. From e69ef2082a81ec860ceb24d38f4551a74f29bb79 Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Wed, 1 Jul 2026 12:36:49 +0700 Subject: [PATCH 3/8] Review fix: targeted removal instead of unsafe jq-only check --- docs/breakdown-configuration.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md index cc2b3f63..0dfedfdf 100644 --- a/docs/breakdown-configuration.md +++ b/docs/breakdown-configuration.md @@ -149,13 +149,14 @@ cat ~/.opencode/opencode.json 2>/dev/null cat ~/.opencode/tui.json 2>/dev/null ``` -**To remove only the plugin entry (not the whole file)** — if the local files contain other settings beyond the plugin entry, edit the file and remove just `"@cortexkit/opencode-magic-context"` from the `"plugin"` array. If the file contains only the plugin entry or no other useful config, delete the entire file: +**To remove only the plugin entry (not the whole file):** ```bash -# Safe deletion check — only if file consists solely of the plugin entry: -if [ -f ~/.opencode/opencode.json ] && [ "$(jq '.plugin | length' ~/.opencode/opencode.json 2>/dev/null)" = "1" ]; then - rm ~/.opencode/opencode.json - echo "Removed (only plugin entry)" +# Targeted removal — removes just the magic-context entry from the plugin array, +# never deletes the entire file even if it contains other config. +if [ -f ~/.opencode/opencode.json ]; then + jq 'if (.plugin | length) == 1 then del(.plugin) else (.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) end' ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json + echo "Removed magic-context entry from plugin array" fi ``` From 914398912db962585fb6dc2ee40cc75f59d1bc64 Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Wed, 1 Jul 2026 12:42:59 +0700 Subject: [PATCH 4/8] Greptile fixes: jq filter-then-check + canonical install path --- docs/breakdown-configuration.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md index 0dfedfdf..8ccf3d16 100644 --- a/docs/breakdown-configuration.md +++ b/docs/breakdown-configuration.md @@ -155,7 +155,9 @@ cat ~/.opencode/tui.json 2>/dev/null # Targeted removal — removes just the magic-context entry from the plugin array, # never deletes the entire file even if it contains other config. if [ -f ~/.opencode/opencode.json ]; then - jq 'if (.plugin | length) == 1 then del(.plugin) else (.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) end' ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json + # Always filter first, then del only if nothing remains. +jq '(.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) | if (.plugin | length) == 0 then del(.plugin) else . end' \\ + ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json echo "Removed magic-context entry from plugin array" fi ``` @@ -166,13 +168,13 @@ Keep plugin in only one scope. **Symptom:** Plugin listed in config but OpenCode shows loading errors. -**Solution:** Install manually to cache: +**Solution:** Re-install with the proper command: ```bash -cd ~/.cache/opencode && npm install @cortexkit/opencode-magic-context --ignore-scripts +opencode plugin @cortexkit/opencode-magic-context --global ``` -Or re-install with `opencode plugin @cortexkit/opencode-magic-context --global`. +This installs to the canonical cache path (`~/.cache/opencode/packages/@cortexkit/`). Only use manual `npm install` inside `~/.cache/opencode` as a last resort — it installs to `node_modules/` which the package cache table above notes is **not canonical** and may not be discovered by OpenCode. --- From 27dd07de6d1b11639f449ac6e4e9bbda78431e80 Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Wed, 1 Jul 2026 14:05:14 +0700 Subject: [PATCH 5/8] Fix bash line continuation: double backslash -> single --- docs/breakdown-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md index 8ccf3d16..b8eb75e2 100644 --- a/docs/breakdown-configuration.md +++ b/docs/breakdown-configuration.md @@ -156,7 +156,7 @@ cat ~/.opencode/tui.json 2>/dev/null # never deletes the entire file even if it contains other config. if [ -f ~/.opencode/opencode.json ]; then # Always filter first, then del only if nothing remains. -jq '(.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) | if (.plugin | length) == 0 then del(.plugin) else . end' \\ +jq '(.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) | if (.plugin | length) == 0 then del(.plugin) else . end' \ ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json echo "Removed magic-context entry from plugin array" fi From aaf4fb2119bf01f78b69435d46578bc10a55ce25 Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Wed, 1 Jul 2026 14:48:07 +0700 Subject: [PATCH 6/8] =?UTF-8?q?Fix:=20echo=20inside=20&&=20chain=20?= =?UTF-8?q?=E2=80=94=20only=20prints=20on=20success?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/breakdown-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md index b8eb75e2..609040f8 100644 --- a/docs/breakdown-configuration.md +++ b/docs/breakdown-configuration.md @@ -158,7 +158,7 @@ if [ -f ~/.opencode/opencode.json ]; then # Always filter first, then del only if nothing remains. jq '(.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) | if (.plugin | length) == 0 then del(.plugin) else . end' \ ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json - echo "Removed magic-context entry from plugin array" + echo "Removed magic-context entry from plugin array" && : fi ``` From 762463aeff36913214999956cae385d48690f9ba Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Wed, 1 Jul 2026 14:48:29 +0700 Subject: [PATCH 7/8] =?UTF-8?q?Fix:=20chain=20echo=20onto=20mv=20with=20&&?= =?UTF-8?q?=20=E2=80=94=20only=20prints=20on=20success?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/breakdown-configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/breakdown-configuration.md b/docs/breakdown-configuration.md index 609040f8..2280c882 100644 --- a/docs/breakdown-configuration.md +++ b/docs/breakdown-configuration.md @@ -157,8 +157,7 @@ cat ~/.opencode/tui.json 2>/dev/null if [ -f ~/.opencode/opencode.json ]; then # Always filter first, then del only if nothing remains. jq '(.plugin |= map(select(. != "@cortexkit/opencode-magic-context"))) | if (.plugin | length) == 0 then del(.plugin) else . end' \ - ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json - echo "Removed magic-context entry from plugin array" && : + ~/.opencode/opencode.json > /tmp/opencode_tmp.json && mv /tmp/opencode_tmp.json ~/.opencode/opencode.json && echo "Removed magic-context entry from plugin array" && : fi ``` From cc54df170c50d0dab37e43c97446970d745ff287 Mon Sep 17 00:00:00 2001 From: Ev3lynx727 Date: Wed, 1 Jul 2026 14:48:53 +0700 Subject: [PATCH 8/8] Fix: proper && chain for echo (remove stale && :)