feat(claude-code,codex): tell existing users about the Coding Agents plugin - #3205
Closed
nicoloboschi wants to merge 4 commits into
Closed
feat(claude-code,codex): tell existing users about the Coding Agents plugin#3205nicoloboschi wants to merge 4 commits into
nicoloboschi wants to merge 4 commits into
Conversation
…plugin Both plugins still work but development has moved to @vectorize-io/hindsight-coding-agents. Someone who installed one of these a year ago has no way to learn that — a changelog entry reaches nobody — so the session itself says it, once, via the SessionStart hook's systemMessage (the channel the USER sees; additionalContext would only reach the model). Codex accepts Claude Code's hook output shape, so one design serves both. Restraint is the point: - capped at 3 showings total, never more often than every 7 days, so it cannot become a recurring interruption - `"upgradeNotice": false` in the user config silences it permanently, and the message says so - every failure path returns None instead of raising: unreadable state, an unwritable state dir, a corrupt timestamp. A promotional message must never be the reason a session breaks Emitted before the existing early returns, since neither the memory settings nor whether the server is reachable changes the fact that the plugin is superseded. The module is duplicated rather than shared — these ship as independent packages with no common module path, and ~40 lines is cheaper than inventing one.
Shown once every session instead of three times a week apart: a notice that appears once is a notice that gets missed, and this one has a concrete action attached. `"upgradeNotice": false` is what keeps that acceptable — it turns the notice off permanently and the message says so. Also links https://hindsight.vectorize.io/sdks/integrations/coding-agents, so the message no longer has to carry the whole story itself. Dropping the rate limit removes the state file, the timestamp parsing and their failure modes with it; what remains is a config check. The never-raise guarantee stays: a promotional message must not be why a session breaks.
…on guide "Superseded by" is jargon that reads as a footnote. The notice now opens by saying the plugin is DEPRECATED and replaced, so a user reads one word and knows to act. It also says WHY the replacement is better rather than only that it exists: one install across ten agents, one memory per repo they all share (context from any agent is there for the next), knowledge pages kept current from git history, automatic seeding, and a daemon mode needing no account. The link now deep-links the migration section rather than the page — someone who has just been told to move wants the steps, not the pitch. Verified the anchor resolves on the live site.
Drops the install commands and the feature list: the migration guide carries both, and a shorter message is likelier to be read. Adds the Knowledge Page capability and its v0.9.x server requirement, which the earlier text left out — that is the part someone on an older server needs to know before switching. Tests follow the text: the install-command and package-name assertions are gone (neither appears in the message any more), replaced by one that the message names WHICH plugin is deprecated, since both can be installed side by side.
nicoloboschi
added a commit
that referenced
this pull request
Aug 7, 2026
Folded in from #3205 so the launch lands as one change: the docs that announce the Coding Agents plugin and the in-session notice that points existing users at them ship together, rather than one arriving without the other. Both plugins keep working, but they are deprecated — development has moved to @vectorize-io/hindsight-coding-agents. A changelog entry reaches nobody who installed a year ago, so the SessionStart hook says it, via systemMessage (the channel Claude Code shows the USER; additionalContext would only reach the model). Codex accepts the same hook output shape, so one design serves both. Emitted before the existing early returns: neither the memory settings nor whether the server is reachable changes the fact that the plugin is deprecated. Shown every session, with `"upgradeNotice": false` as the permanent opt-out — stated in the message itself, which is what makes that frequency acceptable. With no rate limit there is no state file and none of its failure modes; what remains is a config check that returns None rather than raising, because a promotional message must never be why a session breaks.
Collaborator
Author
|
Folded into #3162 (commit 36e1f51) so the launch ships as one change — the docs announcing the Coding Agents plugin and the in-session notice pointing existing users at them land together rather than one arriving without the other. The four wording-iteration commits were squashed into one; the code is identical, and both suites pass on the target branch (204 claude-code, 98 codex). Closing in favour of #3162. |
nicoloboschi
added a commit
that referenced
this pull request
Aug 7, 2026
…3162) * docs: launch the Coding Agents page and mark the per-agent plugins superseded Hold until the Coding Agents plugin is announced — merging this makes the page public and tells existing users their plugin is legacy, so it should land with the announcement rather than before it. Two halves: - Launch. Undoes the deliberate hide: the page drops `unlisted`, its entry returns to integrations.json (which drives both the gallery and the sidebar), and coding-agents leaves the EXCLUDED set in check-integrations.mjs, so the released-tag check guards it like every other integration. - Supersede. The six overlapping integrations — claude-code, codex, opencode, cursor-cli, cline, copilot-cli — get an admonition in the style already used on the Hermes page: what replaces them, the install command for their harness, and a link to the migration section. Pages and packages keep working; nothing is deleted and no registry deprecation is published, so existing links and installs are unaffected. Each notice states plainly that memory does not move — the old plugins scope a bank per agent per project where this one uses a bank per repo — and points at `--import-conversations` for Claude Code and Codex, the two whose transcripts record enough to attribute a session to a repo. The other four say so instead of implying an import exists. * docs: group the integrations sidebars into coding agents / frameworks / apps Both sidebars driven by integrations.json rendered one flat run of 59 entries. Split them into three groups so a coding agent is distinguishable from an SDK. The existing `category` field couldn't drive this on its own: its `tool` bucket mixed CLI agents and editors with chat apps, note-taking and voice platforms. The 19 coding agents move to a new `coding-agent` category; `framework` is unchanged, and `tool`/`mcp` become the catch-all group. Grouping lives in src/lib/integration-groups.ts, kept free of the @site alias and of any JSON import so both consumers can use it — the theme swizzle (webpack) and sidebars-integrations.ts (evaluated at config load). An unrecognised category falls into the last group rather than disappearing from the sidebar. * docs: regenerate the docs-skill mirror for the supersede admonitions scripts/generate-docs-skill.sh mirrors docs-integrations/ into skills/; the launch commit edited seven pages without re-running it, so the mirror still described the per-agent plugins as current. * docs: spell out the migration path for Claude Code and Codex Both pages said memory "does not move automatically", which is now only half true: the server endpoint IS carried over (~/.hindsight/claude-code.json and ~/.hindsight/codex.json, same keys), so nobody is silently switched to Cloud. Each page now states what moves — the endpoint automatically, conversations via --import-conversations — and what does not: the recall/retain settings, missions and bank-naming options. It also says why conversations come from local transcripts rather than the old bank: that bank defaulted to a single static bank shared by every project, whose documents record only a session id, so attributing them to a repo requires the local transcripts regardless. These are the only two superseded plugins with an endpoint to carry; the other four pages already say their history can't be imported and are unchanged. * feat(claude-code,codex): deprecation notice in the old plugins' sessions Folded in from #3205 so the launch lands as one change: the docs that announce the Coding Agents plugin and the in-session notice that points existing users at them ship together, rather than one arriving without the other. Both plugins keep working, but they are deprecated — development has moved to @vectorize-io/hindsight-coding-agents. A changelog entry reaches nobody who installed a year ago, so the SessionStart hook says it, via systemMessage (the channel Claude Code shows the USER; additionalContext would only reach the model). Codex accepts the same hook output shape, so one design serves both. Emitted before the existing early returns: neither the memory settings nor whether the server is reachable changes the fact that the plugin is deprecated. Shown every session, with `"upgradeNotice": false` as the permanent opt-out — stated in the message itself, which is what makes that frequency acceptable. With no rate limit there is no state file and none of its failure modes; what remains is a config check that returns None rather than raising, because a promotional message must never be why a session breaks. * docs: per-harness install sections, featured hub cards, browsable sidebar Page - One subsection per harness with its logo and a copyable install command, replacing the table: the command is what a reader came for, and a table cell is not copyable. - Title is just "Coding Agents"; the old keyword-stuffed title read as spam in the sidebar and breadcrumbs. - "Ingestion internals (no CLI)" is dropped from the docs page via the existing DROP_SECTIONS mechanism, staying in the README where the contributor-facing audience is. Integrations Hub - A Featured grid pins Coding Agents, Vercel AI SDK and OpenClaw above the rest, and only on the unfiltered view — pinned cards above non-matching search results would read as noise. - The Coding Agents card draws all ten supported harness logos. "One install, every agent" is the whole pitch and a single icon cannot carry it. - Logos come from the control plane's harness set, which is already keyed by the exact harness ids the plugin uses, so the two stay consistent by construction. Sidebar - Groups are open but show six entries each, with the tail behind a nested "Show all N". Fully expanded, 59 entries were a wall; fully collapsed hid that the list was worth opening. - The umbrella Coding Agents entry leads its group instead of sorting under "C", since it is the entry point to every other agent in that list. * fix(docs): point the page's harness logos at this build, not production The README must use absolute URLs so the logos render on npm and GitHub, but the docs page inherited them verbatim — pinning every image to hindsight.vectorize.io, where /img/harness/* does not exist yet. Logos were broken locally and in previews, and would only start working after a deploy. The sync script now rewrites our own absolute asset URLs to site-relative, next to the repo-relative-link rewrite it already does for the same reason: two audiences needing different URLs from one source. * docs: curate the sidebar previews, harness logos for coding agents The coding-agent group now previews HARNESSES, not pages: ten logos that all link to the Coding Agents page. Listing ten integration pages there presented one plugin as ten separate integrations, which is the opposite of its pitch — and the logos make the group recognisable at a glance. Every individual page moves behind "Show all", which is also what keeps it associated with the sidebar. The other groups get hand-picked previews instead of the first six alphabetically — the first names in a sorted list are an accident of spelling, not a description of the group: Frameworks & SDKs — LangGraph/LangChain, Vercel AI SDK, Vercel Chat, Eve, CrewAI Apps & tools — ChatGPT, Hermes, OpenClaw, Obsidian Hermes, NemoClaw, OpenClaw and Paperclip move from framework to tool. The overflow label counts what opening it actually reveals: "Show 21 more" where some entries are already previewed above, "Show all 19" for coding agents, whose overflow really is every page. * docs: inline sidebar preview, full list on the integration pages The two sidebars do different jobs, so they now show different things. Main docs sidebar — a preview: three groups rendered INLINE and non-collapsible, nothing behind a disclosure. Ten harness logos for coding agents, five frameworks, four apps, then an "All integrations" link to the gallery, which offers search and filters a sidebar cannot. Integration pages — the full list again: flat, alphabetical, every entry. Once you are on one of these pages you are comparing and hopping between them, so hiding two thirds behind "Show N more" worked against the reader. Listing each page directly is also what associates it with this sidebar. * docs: promote the sidebar groups, separate Featured, brand the umbrella card Sidebar: the "Integrations" placeholder is replaced BY its contents instead of filled, so the three groups sit at the same level as the rest of the navigation. The wrapper was two levels of nesting to say one thing, and it indented every entry beneath it. Hub: a divider and an "All integrations" heading separate the pinned Featured cards from the full list, which otherwise read as one uninterrupted run. The Coding Agents card carries the Hindsight mark rather than the GitHub logo — it is our own package, and the GitHub icon said nothing about it. * docs: install with npx, no global install Every example across the README, the seven integration pages, the companion skill and the generated docs now runs the installer with npx. Nothing here asks anyone to keep a package installed whose only job is to wire other tools up. The paragraph telling people to install globally — and warning that npx was refused — is replaced by what actually happens: install copies what it needs into ~/.hindsight/coding-agents and points each agent's wiring there, so it does not matter where it ran from, and updating is the same command again. Depends on #3241, which makes that staging real; until it ships in 0.0.6 the published installer still refuses to run from an npx cache. * docs: move the superseded pages into a Legacy section, out of the gallery The six per-agent pages the Coding Agents plugin replaces — Claude Code, Codex, Cursor CLI, Copilot CLI, opencode, Cline — move to a `legacy` category. They keep their pages and their migration banners: people still run these plugins and still arrive from old links, so removing the pages would break both. What changes is where they are offered. The gallery is where someone comes to CHOOSE an integration, and offering one we are actively migrating them off points them at a dead end — so legacy entries are filtered out of it, including the hero banner, whose hardcoded list still advertised Claude Code and now advertises the plugin that replaced it. In the sidebar they sit in a collapsed "Legacy" section at the end instead of mixed in alphabetically, so the main list is only what we would recommend today. Docusaurus expands that section automatically when you are on one of the pages. Grouping keys off an explicit `harnessPreview` flag now: "no previewIds" used to imply the coding-agent group, which the Legacy group would also have matched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft — the notice states that the server and token carry over, which is true for Codex only once #3203 merges, and none of it is on npm yet: 0.0.4 predates daemon mode and the endpoint carry-over. This should not merge before a release makes the claims real.
Both plugins keep working, but they are deprecated: development has moved to
@vectorize-io/hindsight-coding-agents. Someone who installed one a year ago has no way to learn that — a changelog entry reaches nobody — so the session says it.What it says
Codex gets the same text with its own plugin name and config path.
Both the page (HTTP 200) and the
#migrating-from-the-per-agent-pluginsanchor are verified live, so the one link a reader is given actually lands on the steps.How
The
SessionStarthook emitssystemMessage, the channel Claude Code shows to the user (additionalContextwould only reach the model). Codex accepts Claude Code's hook output shape, so one design serves both — verified by running each hook and reading its JSON.Emitted before the existing early returns: neither the memory settings nor whether the server is reachable changes the fact that the plugin is deprecated.
Frequency
Every session start. A notice shown once is a notice that gets missed. What makes that acceptable is the opt-out:
"upgradeNotice": falsein~/.hindsight/claude-code.json/codex.jsonturns it off permanently, and the message's last line says so.With no rate limit there is no state file, no timestamp parsing and none of their failure modes — what remains is a config check. The never-raise guarantee stays: a promotional message must never be why a session breaks.
Tests
7 per plugin: shown on five consecutive calls, names which plugin is deprecated (both can be installed side by side), the migration deep-link, that it says DEPRECATED, the opt-out, that the opt-out is discoverable from the message, and that a hostile config object cannot make it raise.
Suites: 204 passed (claude-code), 98 passed (codex).
LINT_ALL_INTEGRATIONS=1 ./scripts/hooks/lint.shclean. Verified end to end that the hook emits it and that the opt-out silences it.The module is duplicated rather than shared — these ship as independent packages with no common module path.