This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
After finishing a change, always git commit every file you modified — do not leave edits sitting uncommitted. Exception: skip committing a file that was already modified by someone/something else (another agent, or the user) before you touched it, since that's in-progress work that isn't yours to commit.
Every feature must ship for EVERY host: the VS Code extension, the Visual Studio 2022/2026 VSIX, the JetBrains-family plugin, the Eclipse plugin, the Apache NetBeans plugin, and the browser demo. Never finish a feature in only some hosts — a feature that exists in only some hosts is incomplete. For every change, one of the first things to check is whether it affects the Eclipse host (eclipse/) and the NetBeans host (netbeans/) — if so, update them in the same change, exactly as you would for VS Code, Visual Studio, and JetBrains.
The JetBrains host is one shared Kotlin codebase that ships as a single build — one plugin, one Marketplace listing, installable across the whole IntelliJ Platform family (IntelliJ IDEA, Android Studio, Huawei DevEco Studio, WebStorm, PyCharm, GoLand, etc.) via an unbounded build-number range, since Marketplace/IDE compatibility is matched by build number rather than product name.
Keep this file in sync: whenever a change touches the code or structure this file describes (a new host or build flavor, a moved/renamed data-layer file, a new build/publish step, a changed command), update the relevant part of CLAUDE.md in the same change — don't leave it describing the old layout.
The renderer/protocol live in shared packages/ (graph-core, graph-webview, protocol) and are consumed by all hosts automatically. But each host has its own data/message layer that must be updated in parallel:
- VS Code (
vscode/, TypeScript):vscode/src/gitData.ts(git ops),vscode/src/panel.ts(message handling). - Visual Studio (
vs/, C#):vs/Git/GitService.cs(git ops),vs/WebViewHostControl.xaml.cs(message handling),vs/Model/Dtos.cs(hand-mirrored protocol types). - JetBrains (
jetbrains/, Kotlin — IntelliJ Platform plugin). All the code is shared injetbrains/common/:jetbrains/common/src/main/kotlin/.../git/GitService.kt(git ops),jetbrains/common/.../WebViewHostPanel.kt(message handling, JCEF host),jetbrains/common/.../model/Dtos.kt(hand-mirrored protocol types). One thin subproject,jetbrains/intellij/, compiles that shared code against a broad IntelliJ Platform baseline and adds only its ownMETA-INF/plugin.xml. - Eclipse (
eclipse/, Java — PDE/OSGi plugin, hosted by the SWTBrowserwidget). Data/message layer undereclipse/com.hunkontech.revgraph/src/com/hunkontech/revgraph/:git/GitService.java(git ops, git CLI viaProcessBuilder),WebViewHost.java(message handling; JS→host is an SWTBrowserFunctionreusing the samewindow.__ideHostPostMessage__hook the JetBrains/JCEF host uses),model/Dtos.java(hand-mirrored protocol types), plusutil/Json.java(a tiny dependency-free JSON codec so the bundle needs no Gson). The plugin is built with Eclipse Tycho into a p2 update site (feature + repository subprojects). - NetBeans (
netbeans/, Kotlin — NetBeans module / nbm-maven-plugin, hosted by a JavaFXWebViewembedded in a SwingJFXPanel). This host maximizes shared code: it does NOT re-implement the git/DTO layer — itsnetbeans/pom.xmlcompiles the JetBrains host's shared, IDE-agnostic Kotlin directly (jetbrains/common/.../git/GitService.kt+.../model/Dtos.kt, both 0-IntelliJ-import), so there is nothing to hand-mirror there. Only the NetBeans platform glue is its own, undernetbeans/src/main/kotlin/com/hunkontech/revgraph/:NetBeansWebViewHost.kt(message handling; JS→host is a JavaFXJSObjectbridge reusing the samewindow.__ideHostPostMessage__hook the JetBrains/JCEF and Eclipse/SWT hosts use — seewebview/bridge.js),RevisionGraphTopComponent.kt(the editor-area window),OpenRevisionGraphAction.kt(Tools-menu action),NetBeansRepoResolver.kt,RepoWatcher.kt. - Browser demo (
packages/graph-webview/harness/demo-host.js): simulates git ops in-browser with mock data; thehandlersobject must mirror everyWebviewToHostmessage type handled by the real hosts. - Any protocol change in
packages/protocol/src/index.tsmust be mirrored by hand intovs/Model/Dtos.csANDjetbrains/common/.../model/Dtos.ktANDeclipse/com.hunkontech.revgraph/src/com/hunkontech/revgraph/model/Dtos.javaAND handled indemo-host.js. The NetBeans host needs no separate mirror — it compilesjetbrains/common/.../model/Dtos.kt, so the JetBrains edit already covers it (just extendNetBeansWebViewHost.kt's dispatcher if a new message type needs handling). - The shared webview bundle is copied into each IDE host by the build (
vscode/media/,vs/webview/,jetbrains/common/src/main/resources/webview/,eclipse/com.hunkontech.revgraph/webview/,netbeans/src/main/resources/com/hunkontech/revgraph/webview/).
The VS C# VSIX is a legacy .NET Framework 4.7.2 + VS SDK project and can only be compiled on Windows (see vs/BUILD.md). On non-Windows machines, review the C# carefully but it cannot be built/run there.
The JetBrains plugin needs a JDK 17 + Gradle + IntelliJ Platform Gradle plugin toolchain (see jetbrains/BUILD.md); one buildPlugin in jetbrains/ produces the plugin ZIP. It's additionally wired for JetBrains Marketplace publishing (opt-in, needs PUBLISH_TOKEN) as a single listing (pluginGroup in jetbrains/gradle.properties) — neither DevEco Studio nor Android Studio has a separate plugin store; both are IntelliJ Platform IDEs, so their Marketplace tabs are the same JetBrains Marketplace, and the one listing's build-number range already covers them. Its git-plumbing-based reword/undo of non-HEAD commits intentionally diverges from the VS host's PowerShell-scripted rebase -i (the plugin is cross-platform); see the doc comments on GitService.kt's rewordCommit/undoCommit.
The Eclipse plugin needs a JDK 17 + Maven + Eclipse Tycho toolchain with network access to the Eclipse p2 repositories (see eclipse/BUILD.md); one mvn -f eclipse/pom.xml package produces the OSGi plugin, an installable feature, and a p2 update site (+ zip). Its Java data layer is a faithful hand-port of the JetBrains Kotlin one (same git-plumbing reword/undo, hence the same clean-working-tree requirement). Unlike the other marketplaces, the Eclipse Marketplace hosts no artifact — a listing just references a p2 update-site URL, so "publishing" means deploying that update site (CI attaches the zipped site to the GitHub Release and pushes the live site to GitHub Pages). Like the VS VSIX and JetBrains plugins, the Eclipse plugin is authored cross-platform but is not built in this sandbox (Tycho needs the network target platform).
The NetBeans plugin needs a JDK 17 + Maven + nbm-maven-plugin toolchain plus the bundled JavaFX WebView runtime (see netbeans/BUILD.md); one mvn -f netbeans/pom.xml package produces the sideloadable .nbm. It is a Kotlin module that reuses the JetBrains host's shared GitService.kt + Dtos.kt verbatim (the kotlin-maven-plugin adds jetbrains/common/.../git and .../model as extra source roots — the sibling IntelliJ-coupled files are deliberately kept off the source path), and registers its Tools-menu action via the NetBeans annotation processors run through Kotlin kapt. Unlike the JetBrains Marketplace, the Apache NetBeans Plugin Portal has no token-based push API — it only lists plugins hosted on Maven Central and requires a one-time manual "Add Plugin" registration cleared by two verifiers, so there is no token to publish with. End-user auto-update is instead delivered the NetBeans-native way (mirroring the Eclipse p2 update site): the nbm-maven-plugin autoupdate goal — bound to the package phase in netbeans/pom.xml, distBase left unset so nbm URLs stay relative/location-independent — emits an updates.xml Autoupdate Center into netbeans/target/netbeans_site/, which the build-netbeans-plugin CI job deploys to GitHub Pages under /netbeans-update-center (via peaceiris/actions-gh-pages, keep_files: true, using only the existing GITHUB_TOKEN — no new secret). CI "publishing" therefore means (a) attaching the .nbm to the GitHub Release and (b) deploying that Update Center. Getting onto the optional Plugin Portal listing is a two-parter: the build-netbeans-plugin job also runs an opt-in -Pcentral-deploy Maven Central deploy (the central-deploy profile in netbeans/pom.xml adds sources/javadoc + GPG signing + Sonatype's central-publishing-maven-plugin), gated on the MAVENCENTRAL_USERNAME secret (skipped otherwise; also needs MAVENCENTRAL_PASSWORD + MAVEN_GPG_PRIVATE_KEY + MAVEN_GPG_PASSPHRASE, plus the GitHub-verified Sonatype namespace io.github.benkoncsik — so the Maven groupId is io.github.benkoncsik, module code-name base io.github.benkoncsik.netbeans, even though the source packages/JetBrains pluginGroup/Eclipse bundle ids stay com.hunkontech.revgraph) — then the actual Portal "Add Plugin" (io.github.benkoncsik / netbeans) + two-verifier approval stays a documented one-time manual step (watch two caveats: the module must be certificate-signed, and BSL-1.1 is non-OSI so verifiers may reject it). See netbeans/BUILD.md. Known limitation: NetBeans ships no JavaFX, so the WebView runtime is bundled and the CI .nbm is built for the runner's platform — full multi-platform native bundling is a documented follow-up. Like the other JVM hosts, the NetBeans plugin is authored cross-platform but is not built in this sandbox (needs Maven + JDK 17 + JavaFX).
npm install # install all workspace dependencies
npm test # run all unit tests (vitest, graph-core only)
npm run build # build everything: protocol → graph-core → webview → vscode extension → VS assets → JetBrains assets → Eclipse assets → NetBeans assets
npm run harness # browser dev harness with mock data at http://localhost:5599
npm run translate:i18n # fill in i18n.ts translations locally (en+hu always excluded); add -- --force to redo allnpm run translate:i18n wraps scripts/translate-i18n.sh, which runs
KO_language_translator/main.py against packages/graph-webview/src/i18n.ts —
the same call the Translate i18n workflow makes (4 parallel workers). en
and hu are never translated; -- -x fr,de skips more, -- -j 8 changes the
worker count.
Run a single test file:
npx vitest run packages/graph-core/src/layout.test.tsBuild individual packages in dependency order:
npm run build:core # compiles packages/protocol + packages/graph-core (tsc -b)
npm run build:webview # bundles packages/graph-webview (esbuild via build.mjs)
npm run build:vscode # compiles vscode/ extension (esbuild)
npm run build:vs-assets # copies webview bundle into vs/ (node scripts/copy-vs-assets.mjs)
npm run build:jetbrains-assets # copies webview bundle into jetbrains/common/ (node scripts/copy-jetbrains-assets.mjs)
npm run build:eclipse-assets # copies webview bundle into eclipse/ (node scripts/copy-eclipse-assets.mjs)
npm run build:netbeans-assets # copies webview bundle into netbeans/ (node scripts/copy-netbeans-assets.mjs)Package for distribution:
npm run package:vscode # → dist/installers/*.vsix (cross-platform)
npm run package:eclipse # → eclipse p2 update site + zip (mvn/Tycho; needs JDK 17 + network)
npm run package:netbeans # → netbeans/target/*.nbm (mvn + nbm-maven-plugin; needs JDK 17 + JavaFX)
pwsh scripts/build-installers.ps1 # all installers: VS Code, VS 2022/2026, all three JetBrains ZIPs, NetBeans .nbm (Windows only)VS Code extension dev loop: npm run build then press F5 in VS Code (Extension Development Host). No watch mode is wired to F5 — rebuild manually after changes.
This is a monorepo with one shared web renderer embedded by several thin IDE hosts:
packages/protocol/ — shared TypeScript types: GitCommit, GitRef, GraphData, WebviewToHost, HostToWebview
packages/graph-core/ — pure DAG layout algorithm (no DOM, fully unit-tested)
packages/graph-webview/ — SVG renderer + context menus + i18n (builds to one JS bundle)
vscode/src/ — VS Code extension: git data layer, webview panel, git CLI wrappers
vs/ — Visual Studio C# extension (WebView2 host, mirrors the TS protocol by hand)
jetbrains/ — JetBrains-family plugin (Kotlin, IntelliJ Platform, JCEF host, mirrors the TS protocol by hand).
Multi-project: shared code in jetbrains/common/, one plugin subproject
jetbrains/intellij/ (installable across IntelliJ IDEA, Android Studio, DevEco Studio, etc.)
eclipse/ — Eclipse plugin (Java, PDE/OSGi, SWT Browser host, mirrors the TS protocol by hand).
Tycho reactor: com.hunkontech.revgraph (plugin), .feature, .repository (p2 update site)
netbeans/ — Apache NetBeans plugin (Kotlin, NetBeans module, JavaFX WebView host).
REUSES the JetBrains host's shared git/DTO Kotlin (jetbrains/common/.../git + model);
only the platform glue is its own. Built with Maven + nbm-maven-plugin → .nbm
- Host reads git (
vscode/src/gitData.ts: readGraphData) — callsgit logandgit for-each-ref, parses output intoGraphData(commits[]+refs[]+head). - Host → webview via
panel.ts: GraphPanel.post({ type: "setData", data }). - Webview layout (
packages/graph-core/src/layout.ts: computeLayout) — assigns each commit a(row, lane)using a TortoiseSVN-style branch-column algorithm. Input commits must be newest-first (git log --date-order). Output:PositionedCommit[]+LayoutEdge[]. - Webview render (
packages/graph-webview/src/render.ts: GraphView) — draws the layout as SVG boxes and edges. Supports two display modes ("modern" free canvas, "classic" scroll-only with trunk pinned left), stored inlocalStorage. - User actions (context menu, double-click) →
WebviewToHostmessage →panel.ts: onMessage→ git CLI calls ingitData.ts.
packages/protocol/src/index.ts defines all message shapes. The C# Visual Studio host mirrors these by hand — any change here must be reflected in vs/ too.
Key message types:
HostToWebview:setData|setTheme|branchCreated|opResult|commitChanges|commitTree|treeContentSearchResults|fileDiff|fileContent|workingTreeChanges|workingTreeFileDiff|commitCreated|mergePreview|mergeFileDiff|searchResults|searchError|gitPathSelected|errorWebviewToHost:ready|requestRefresh|createBranch|deleteBranch|renameCommit|requestCommitChanges|requestCommitTree|requestTreeContentSearch|requestFileDiff|requestFileContent|requestWorkingTreeChanges|requestWorkingTreeFileDiff|commitWorkingTreeChanges|checkout|copySha|fetch|pull|push|sync
packages/graph-webview/src/:
main.ts— entry point; wiresGraphViewcallbacks to bridge messages; owns the toolbar and settings panelrender.ts: GraphView— SVG rendering class;setData(layout, head)redraws everythingi18n.ts— inlineDICTSobject, one dict per language, witht(key, params?)helper;localStorage-persisted; subscribe viaonLangChange(cb).enandhuare hand-maintained; every other language is filled in automatically byKO_language_translator/main.py(Google Translate). The Translate i18n workflow (.github/workflows/translate-i18n.yml) runs on every push (nopaths:filter) and is the single entry point of the release chain: push → Translate i18n → Build & Publish Extensions (release.yml) → Deploy demo (deploy-demo.yml), each link wired byworkflow_runon the previous one's completion (neitherrelease.ymlnordeploy-demo.ymlhas a directpushtrigger any more). When a push doesn't touchi18n.ts/KO_language_translator// the workflow itself, Translate i18n's "Decide whether translation is needed" step (id: need) short-circuits the heavy steps but the workflow still finishes green so the chain fires. When it does translate, it commits the result back with[skip ci](which would otherwise re-trigger the chain).release.ymlonly proceeds when the upstream run'sconclusion == 'success'(or on manualworkflow_dispatch); itsreleasejob's "Sync to latest main" step (id: sync) just doesgit reset --hard origin/main(the translation commit, if any, is already there — no polling) and exports that SHA asbuild_sha, which every downstream build job checks out. Runner for the Translate i18n workflow is declared via theRUNNER_TRANSLATErepo variable (any self-hosted OS), GitHub-hosted fallback.contextMenu.ts— lightweight DOM context menu (showContextMenu,MenuItem[])host-bridge.ts— abstractsvscode.postMessage/window.__REV_GRAPH_HARNESS__(for the browser harness)settings.ts,displayMode.ts,mainBranch.ts— each owns onelocalStorage-backed setting + change-listeners
vscode/src/:
extension.ts— registersrevGraph.showandrevGraph.refreshcommandspanel.ts: GraphPanel— singleton webview panel; handles allWebviewToHostmessages; calls git functions; auto-refreshes on repo state changesgitData.ts— all git operations viaexecFile(never shell); uses\x1f/\x1efield/record separators to parsegit logoutput safelybranch.ts: createBranchFromCommit— branch creation; triesvscode.gitAPI first, falls back to CLIrepo.ts— resolves the activeRepositoryfrom thevscode.gitextension API
- Input must be newest-first (children before parents).
lane 0= main branch (configurable, defaults tomain/master/HEAD).- Branches share a lane when their row intervals don't overlap (interval scheduling).
- Phantom nodes: a branch tip that points at the same commit as another branch gets a synthetic node (same
sha, uniquenodeId) so each branch always has its own box. remoteOnly: a commit reachable only from remote-tracking refs is flagged; the renderer colors it distinctly without moving it off its branch's lane.
- Add a new variant to
WebviewToHostinpackages/protocol/src/index.ts. - Add i18n keys to both
enandhudicts inpackages/graph-webview/src/i18n.ts. - Add the menu item in
packages/graph-webview/src/main.ts(onNodeContextMenu). - Handle the message in
vscode/src/panel.ts: onMessage. - Implement the git operation in
vscode/src/gitData.ts. For new working-tree commit flows, add the same list/diff/commit trio asrequestWorkingTreeChanges,requestWorkingTreeFileDiff, andcommitWorkingTreeChanges. - Mirror the protocol change in
vs/(C# side):vs/WebViewHostControl.xaml.cs+vs/Git/GitService.cs+vs/Model/Dtos.cs. - Mirror the protocol change in
jetbrains/(Kotlin side):jetbrains/common/.../WebViewHostPanel.kt+jetbrains/common/.../git/GitService.kt+jetbrains/common/.../model/Dtos.kt. - Mirror the protocol change in
eclipse/(Java side):eclipse/com.hunkontech.revgraph/src/com/hunkontech/revgraph/WebViewHost.java+.../git/GitService.java+.../model/Dtos.java(newWebviewMessagefields go inDtos.java'sfromJson). - For
netbeans/(Kotlin side): the git op and DTO change are already covered — steps 5 & 7 edit the sharedjetbrains/common/.../git/GitService.kt+.../model/Dtos.ktthat the NetBeans module compiles. Only extendnetbeans/src/main/kotlin/.../NetBeansWebViewHost.kt'sdispatch()to handle the new message type. - Add a simulated handler in
packages/graph-webview/harness/demo-host.js(handlersobject) — the demo runs entirely in the browser with no real git, so every action needs its own mock implementation.
All git calls go through the private git(cwd, args[]) helper in gitData.ts, which wraps execFile (no shell injection risk). Errors propagate as thrown Error objects; callers wrap them in try/catch and post { type: "error", message } back to the webview.
The git binary path is set by setGitPath() from the VS Code built-in Git extension (so users never need a separate git install).