arboretum/packages/vscode/README.md

Arboretum for VS Code

Pilot your git worktrees and Claude Code sessions from inside VS Code: a real native integration on top of the Arboretum daemon, not a webview.

• Live tree of Repositories → Worktrees → Sessions (and a Groups view), updated in real time over the daemon's WebSocket.
• Native terminals: attach to any session in a real VS Code terminal (a Pseudoterminal bridges the daemon's PTY): you get VS Code's own rendering, scrollback, copy/paste and links for free.
• Waiting alerts: a status-bar counter and native notifications when a Claude session is waiting for input: answer Yes/No without even opening the terminal (uses the daemon's answer command).
• Git mutations from the tree: create worktree, commit, push, fetch, pull, promote to main, with a detailed git status on each worktree (staged / unstaged / conflicts and the last commit subject).
• Open Worktree IDE: jump from any worktree into the multi-project IDE (unified project / worktree / session tree, tabbed Monaco editor with inline diffs, docked terminals), in the browser or the native desktop app. The extension stays a lightweight visual worktree manager: the heavy editing lives in the IDE.
• Workspace-aware: the worktree matching your open folder is highlighted; start a session or create a worktree for the current folder in one command.

Requirements

• A running Arboretum daemon (npx @johanleroy/git-arboretum, or installed as a user service via arboretum install). The extension is a client: it does not start the daemon.
• An access token. The bootstrap token is printed once on first daemon start; you can also create one in the Arboretum dashboard (Settings → Tokens).

Getting started

1. Start the daemon and copy a token.
2. In VS Code, run Arboretum: Sign In (Command Palette) and paste the token. The token is validated against the daemon and stored in VS Code's encrypted SecretStorage.
3. The Arboretum view container appears in the Activity Bar with the Repositories and Groups trees.

Settings

Setting	Default	Description
arboretum.url	http://127.0.0.1:7317	Base URL of the daemon (REST + WebSocket).
arboretum.showExternalSessions	false	Also show Claude sessions started outside Arboretum (CLI).
arboretum.showArchivedSessions	false	Also show finished sessions auto-archived after their retention window.
arboretum.notifyOnWaiting	true	Native notification when a session starts waiting for input.

The extension authenticates with Authorization: Bearer <token> on both REST and the WebSocket upgrade. For remote access, point arboretum.url at your Tailscale Serve URL (https://…): the WebSocket is derived automatically (wss://).

Building & packaging (private VSIX)

The extension is bundled with esbuild (@arboretum/shared is inlined → the VSIX is self-contained).

# from the monorepo root
npm install
npm run build:vscode                       # builds @arboretum/shared then bundles the extension
cd packages/vscode && npx @vscode/vsce package --no-dependencies
# → git-arboretum-<version>.vsix

Install it with Extensions: Install from VSIX… in the Command Palette, or:

code --install-extension git-arboretum-<version>.vsix   # also: codium / cursor

Other distribution channels (optional)

• Open VSX (VSCodium, Cursor, Windsurf): npx ovsx publish *.vsix -p <token> after creating an Open VSX account and namespace.
• VS Code Marketplace: create an Azure DevOps publisher + PAT, then npx @vscode/vsce publish.

A Gitea Actions workflow packages the VSIX automatically on a vscode-vX.Y.Z tag (see .gitea/workflows/vscode-release.yml) and attaches it to the release.

Security

The extension never weakens the daemon's security model: it speaks the same authenticated protocol as the web dashboard. A Node client sends no Origin header, so it passes the daemon's strict Origin check while still requiring a valid token.