opencode-context-tree 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+## 0.1.0 — 2026-09-03
+
+First working version, built against OpenCode 1.18.26.
+
+- `/tree` (`ctrl+q`, `/ctree`, `/panel`): combined tree + trajectory view — spine rows with a
+  git-log gutter, fold/expand branches, jump (switch or fork with Pi's summarize-on-leave
+  picker), labels, filters, search, Input/Model/Tools lanes with Duration/Turns/Calls
+  modes, inspector pane, consumers view.
+- The branch you are in is drawn at its fork point as `╰⎇ name … ← here`, with its own rows
+  nested under it — so a freshly forked session no longer looks exactly like its trunk.
+- `/branch`, `b`: fork into a named branch, optional model per branch (applied by the
+  server half).
+- `/merge`, `m`: squash to a human-confirmed ◆ decision record via `$EDITOR` (or in-app
+  confirm), squash without LLM, discard, tournament; `/decisions`, `D`, export to markdown.
+- `c` crop mode: stub tool results or drop whole turns from the model's context
+  (append-only journal, applied per request by the server plugin), protections, auto rules,
+  `hardCrop` option to also set OpenCode's compacted flag.
+- `x` / `/ctree undo`: revert the last crop, branch, or merge on the current path.
+- Gauge on the prompt line with absolute bands, trend and attribution, red-band and
+  compaction-reserve toasts; sidebar card.
+- Native forks (OpenCode's own `/fork`, `session.fork`) are adopted into the tree
+  automatically — matched to their parent by the copied message prefix, journalled as
+  `branch.opened { kind: "native" }` by both halves, and shown under their session title
+  (they have no branch name). Only `… (fork #n)` titles are adopted blindly.
+- Headless `/ctree status|branch|merge --discard|crop|undo|decisions [--export]` for
+  non-TUI clients; `/ctree branch` mirrors the tree linkage into `session.metadata`.
+- Options: `storage`, `jumpSummary`, `hardCrop`, `keybinds` (including `open`).
+- `/tree` is now a Pi-style outline of the whole session tree by default: one content-forward row
+  per message and tool step (`● user:` / `○ assistant:` / `⚙ [bash $ …]`), branches drawn at their
+  fork points with `│ ├ ╰` connectors and folded to their `⎇` header until opened; from any session
+  you see the whole tree, your branch open with `← here`. The DeepSeek-Harness trajectory (Input/
+  Model/Tools lanes, per-step inspector) is off by default and one keystroke away (`1/2/3`, `i`).
+- Off-path branches: siblings and the trunk's continuation that are not on the active path
+  appear as `┆⎇` rows at the bottom of the tree; `→` expands them, `⏎` switches. The trunk's
+  own continuation reads `trunk continues` — it is not a branch of itself.
+- Tool results are costed by size (`~`, chars/4) in rows and totals, so ⚠ fires on fat
+  results; the context gauge counts the last assistant turn's own output, and the header's
+  `~` appears only when part of the total really is a guess.
+- Route keys are inactive while a dialog is open (they used to fire from text typed into the
+  search / branch prompts); the sidebar card refreshes after every journal write; the layout
+  follows terminal resizes; errored tool calls show in the Tools lane.
+- Server half honours `storage` (use the same value in both config files), fetches whole
+  transcripts (OpenCode's message paging cursor is not usable by clients), resolves the state
+  dir without blocking startup, never fails a turn on journal I/O errors, and locks registry
+  writes against the TUI half.
+- `/ctree decisions --export` defaults to `./ctree-decisions.md`; `/ctree branch` names may
+  contain spaces (a trailing `provider/model` picks the branch model); `--min-tokens` /
+  `--older-than` reject non-numbers instead of silently doing nothing.
+- Outside a git repo (OpenCode reports worktree `/`) the journal lives in OpenCode's state
+  dir instead of the filesystem root.
+- Harness: mock provider, pty driver with pyte screen snapshots (`@!regex` keys wait for fresh
+  output), Bun e2e suite; pty runs are sandboxed with their own XDG dirs so they never read
+  your real OpenCode config or write sessions into your real database.
+
+### UX pass over the real screens
+
+- The prompt gauge and the tree header print the identical context string
+  (`ctx ~2.3k/32.8k · low`), so the two surfaces can no longer disagree.
+- Sidebar card: **Context tree** is a heading like OpenCode's own `Context` and `LSP`; the
+  branch name and its status sit on separate lines (a long name used to wrap and orphan
+  `· open`), and the status line names where you came from — `open · from "Fix flaky test"`.
+- Sidebar card: the crops line only appears when there are crops (`✂ 2 crops · ~31k hidden`),
+  and the trunk reads `trunk · 2 branches` when it has any.
+- Merge picker: the title says where the branch is going (`Merge ⎇ try-redis → Fix flaky
+  test`), every option carries a subtitle, and **Tournament** is offered only when the branch
+  has open siblings. The "no `$EDITOR`" fallback no longer leaks into the option labels.
+- Every merge confirmation — the in-app one and the `$EDITOR` gate — states that your
+  transcript is never rewritten and the record is appended to the trunk as a normal message;
+  the file `$EDITOR` opens explains that saving is the confirmation.
+- `/branch` from the palette asks with the same wording as `b` in the tree
+  (`Branch here → new OpenCode session`), and the model picker that follows says
+  `Model for this branch (Enter keeps the current one)`.
+- The tree footer lists the six keys you need (`⏎ go  b branch  m merge  c crop  x undo
+  ? help  q back`); `?` opens a help overlay with how to read the screen and every other key.
+- Rows sit under a `turn  step … tokens` column header, the selected row is drawn with a
+  readable contrast, previews no longer show raw markdown (`**`, backticks), and estimated
+  token counts read `~2.1k` instead of `2.1k~`.
+- The timeline lanes stay hidden until there are three turns to plot; a session with no
+  messages says so instead of drawing an empty frame; a branch you just made reads
+  `just branched, nothing here yet` instead of offering an empty fold.
+- The crop confirmation says what actually happens: the tokens leave the model's context on
+  the next turn, your transcript is never rewritten, `/undo` restores.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naveen (navbytes)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# opencode-context-tree
+
+Pi-style context tree for [OpenCode](https://opencode.ai), with the
+[`pi-context-tree`](https://github.com/navbytes/pi-context-tree) git-style workflow
+(`/branch`, `/merge`, `/crop`, `/undo`) and a DeepSeek-Harness-style trajectory view
+(timeline lanes, per-step tokens — the model's own where it reports them, estimated `~`
+elsewhere — timing, inspector) in one screen.
+
+**Status: 0.1.0 — first release. Install with `"plugin": ["opencode-context-tree"]` in both `opencode.json` and `tui.json` (see `docs/USAGE.md`).**
+Branch, jump, labels, filters, search, crop + undo, squash/discard/tournament merge with a
+`$EDITOR` gate, the timeline lanes, inspector and consumers views, the gauge, and the headless
+`/ctree` commands all work against OpenCode 1.18 and are covered by pty-driven e2e tests
+(`bun run test:e2e`). Read [DESIGN.md](./DESIGN.md) — it contains the research
+(Pi, `pi-context-tree`, OpenCode plugin/SDK surface, existing plugins, DSH
+trajectory), the end-user flows, the combined tree + trajectory mockup, the data
+model, architecture, edge cases, and the roadmap.
+
+## The idea in one screen
+
+`/tree` is an outline of the whole session tree — Pi's tree — where every message and tool step
+is one content-forward row and branches are drawn at their fork points:
+
+```
+┌ Context tree · Fix flaky test · trunk                                  ctx ~46k/200k · filling
+│ filter: default 24 rows
+│ ● user: build yourself a tool that reads the context window…                              ~1.2k
+│ ○ assistant: I'll start by inspecting my environment…                                      0.3k
+│ ⚙ [bash $ ls -la ~/Documents/] → total 744 …                                              ~2.1k
+│ ● user: decompress the session and show the structure                                      ~0.2k
+│ ╰⎇ try-redis  ▸ squashed · 9 turns                                                          ~22k
+│ ╰⎇ fix-flaky  ▾ open · 6 turns  ← here                                                      ~14k
+│ │ ● user: the bun test is flaky, find the race                                             ~0.4k
+│ │ ⚙ [bash $ bun test src/foo.test.ts] ⚠                                                     ~4.7k
+│ ◆ Decision: try-redis · Outcome: switched to a write-through cache…                         ~0.9k
+└ ⏎ go  b branch  m merge  c crop  i inspector  1·2·3 lanes  x undo  ? help  q back
+```
+
+Every message and tool call is a row; the gutter draws each branch at the message it was forked
+from; from anywhere you see the whole tree, your current branch open with `← here` and the rest
+folded. It stays close to Pi so the screen is familiar to anyone coming from it. The DeepSeek
+Harness *trajectory* is one keystroke away, not gone: `i` opens the inspector (per-step payload,
+result, timing) and `1/2/3` bring in the Input / Model / Tools lane minimap. Sessions made with
+OpenCode's own `/fork` are adopted into the tree automatically.
+
+## Screenshots
+
+Real OpenCode 1.18 TUI, gemma4 via ollama. `/tree` opens as a Pi-style outline of the whole
+session tree: one content-forward row per message and tool step (`● user:` / `○ assistant:` /
+`⚙ [bash $ …]`), branches drawn at their fork points with `│ ├ ╰` connectors and folded to their
+`⎇` header until you open them. Here a trunk about caching a `/users` endpoint has a squashed
+`try-redis` branch (its ◆ decision record is the leaf), a rejected `try-lru`, and two native
+`/fork` sessions:
+
+![tree from the trunk](docs/screenshots/tree-trunk.png)
+
+The DeepSeek-Harness trajectory is one keystroke away, not gone: `i` opens the inspector and
+`1/2/3` bring in the Input/Model/Tools lanes:
+
+![tree with the trajectory panels on](docs/screenshots/tree-trajectory.png)
+
+From inside a branch, `← here` marks your current step, that branch is expanded, and the rest of
+the tree stays visible and folded — you always see the whole tree:
+
+![tree from a branch](docs/screenshots/tree-from-a-branch.png)
+
+`→` expands a branch inline (its turns continue the numbering from the fork point):
+
+![a branch expanded inline](docs/screenshots/tree-expanded.png)
+
+`D` decisions · `u` what's filling the context · `?` help · `m` merge · the sidebar card:
+
+| | |
+|---|---|
+| ![decisions](docs/screenshots/decisions.png) | ![consumers](docs/screenshots/consumers.png) |
+| ![help](docs/screenshots/help.png) | ![merge picker](docs/screenshots/merge-picker.png) |
+
+![sidebar card](docs/screenshots/sidebar-card.png)
+
+## Try it from source
+
+```sh
+bun install && bun run build
+# opencode.json  →  "plugin": ["/abs/path/opencode-tree/dist/server.js"]
+# tui.json       →  "plugin": ["/abs/path/opencode-tree/dist/tui.js"]
+```
+
+The footer inside `/tree` carries six keys — `⏎` go, `b` branch, `m` merge, `c` crop,
+`x` undo, `q` back — and `?` opens a help overlay with the rest: crop mode (`space` mark,
+double for protected, `a` auto, `t` result⇄turn, `⏎` apply), `i` inspector, `u` consumers,
+`D` decisions (`E` export), `L` label, `←→` fold/unfold, `[ ]` hop branches, `f` filter,
+`/` search, `g/G`, and how to read the screen.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/tree` (`Ctrl+Q`) | open the combined tree + trajectory view |
+| `/branch <name> [model]` | fork here into a named branch, optionally on a cheaper model |
+| `/merge [--pick \| --no-llm \| --discard \| --tournament]` | close the branch: **Squash** drafts a ◆ decision record you confirm, **Squash without LLM** lets you write it, **Discard** lands nothing, **Tournament** keeps one of several siblings. Your transcript is never rewritten; the record is appended to the trunk as a normal message |
+| `/crop [--top \| --auto …]` | stub fat tool results or drop whole turns from what the model sees; append-only, reversible |
+| `/undo` | revert the last branch / merge / crop |
+| `/decisions [--export]` | list or export decision records |
+
+## How it maps onto OpenCode
+
+- a **branch is an OpenCode session** created with `session.fork`; the plugin
+  remembers `(parent, anchor)` in an append-only journal and mirrors it into
+  `session.metadata`;
+- **crop** is applied per request in `experimental.chat.messages.transform`, so the
+  transcript keeps the originals and the model sees stubs;
+- **merge** writes the confirmed record with `session.prompt({ noReply: true })`;
+- the UI is a TUI plugin (`@opencode-ai/plugin/tui`): a route, two slots (gauge,
+  sidebar card), dialogs and a keymap layer.
+
+Two config entries will be needed once it ships:
+
+```jsonc
+// opencode.json
+{ "plugin": ["opencode-context-tree"] }
+// tui.json
+{ "plugin": ["opencode-context-tree"] }
+```