Banyan

Banyan is a local-first Electron command center for running Claude Code across many Git worktrees without losing the thread.

It is built for developers who keep several branches in motion at once: review a merge request in one worktree, ask Claude to fix a failing pipeline in another, keep terminals alive while switching context, and see which sessions need attention before they stall.

Highlights

• Manage multiple root repositories and their Git worktrees from one desktop app.
• Start Claude Code or a shell inside any worktree and keep the session alive while you move around.
• Track session state such as active, needs attention, completed recently, failed, and stopped.
• Review branch status, changed files, diffs, and merge request context without leaving the app.
• Create new worktrees with an optional initial Claude prompt.
• Connect GitLab for merge request status, pipeline state, approvals, unresolved discussions, and review comments.
• Send GitLab review comments or failed pipeline context straight into an existing Claude session.
• Connect Jira and turn ticket context into implementation or review prompts.
• Enable a token-protected remote console for checking sessions away from the desktop app.
• Keep local app state on disk while storing GitLab and Jira tokens with Electron safeStorage.

Status

Banyan is an early developer tool. The core local workflow is implemented, but the app still assumes a technical user, a local Claude Code install, and a willingness to run from source while packaging settles down.

Requirements

• Node.js 20 or newer.
• npm.
• Git.
• Claude Code available as claude on your PATH, or a custom command configured in Banyan settings.
• Platform build tools for node-pty if your install needs to rebuild native modules.

GitLab and Jira integrations are optional. The app works as a local worktree and terminal manager without them.

Quick Start

git clone git@github.com:c0dr/banyan.git
cd banyan
npm install
npm run dev

If terminal sessions fail to start after installing dependencies, rebuild the Electron native modules:

npm run rebuild:native

Common Commands

Command	Description
npm run dev	Build the Electron main and preload bundles, start the Vite renderer, and open the desktop app.
npm run build	Type-check and build the desktop app, remote console, and MCP server bundle into out/.
npm run preview	Build and launch the packaged production output with Electron.
npm run dist	Build distributable artifacts with electron-builder.
npm run smoke:pty	Verify that Electron can start a PTY.
npm run screenshot:readme	Rebuild and capture docs/assets/banyan-screenshot.png using seeded demo data.

Using Banyan

1. Open the app and add a root Git repository.
2. Select a worktree from the left sidebar, or create a new one from the app.
3. Start Claude Code or a shell in that worktree.
4. Use the right panel to inspect branch status, diffs, Jira ticket context, and GitLab merge request state.
5. Let Banyan surface sessions that need input, approvals, or follow-up.

By default, new worktrees are created beside the root repository. For example, a root repo at /workspace/banyan creates worktrees under /workspace/banyan-worktrees/<name>.

Remote Console

Banyan can expose a local, token-protected remote console. Enable it in settings, copy the generated token, and open the remote URL shown by the app. The remote console is meant for local-network or tunneled access that you control.

Architecture

app/
  electron/
    main/      # PTY sessions, Git commands, notifications, local state, IPC
    preload/   # Typed renderer bridge
  renderer/    # Desktop React UI
  remote/      # Browser-based remote console
  server/      # Remote API and realtime events
  mcp/         # Banyan MCP tools for Claude sessions
  shared/      # Shared IPC constants, session state, and TypeScript types
scripts/       # Build, dev, smoke test, and screenshot utilities

The renderer does not shell out directly. Filesystem, Git, terminal, token storage, notifications, and remote server behavior live in the Electron main process behind the preload bridge.

Local State and Secrets

Banyan stores non-secret local state in Electron's userData directory, including connected repositories, cached worktrees, archived worktree IDs, preferences, and prompt presets.

GitLab and Jira tokens are stored separately through Electron safeStorage, which uses the operating system credential backend where available, such as macOS Keychain.

Publishing Notes

The package is marked private to avoid accidental npm publication. GitHub is the intended distribution home for now.