overlay

Documentation

Overview

Package overlay makes a pool account dir present the live contents of ~/.claude with writes shared straight back, so a pooled session sees the same projects/skills/settings as plain `claude`. Two interchangeable providers:

• symlink (default + always-available fallback): symlink each top-level entry of ~/.claude into the account dir.
• fuse (preferred when fuse-t is installed; built with -tags fuse): an in-process passthrough mirror mounted via fuse-t.

Both yield the same observable result. A small set of entries is held back from sharing because they are instance-local runtime state that would conflict across concurrent sessions; see ExcludedEntries.

Index

• Variables
• func FuseBuilt() bool
• type Kind
  • func Detect() Kind
• type Provider
  • func For(kind Kind) Provider
• type SymlinkProvider
  • func (p *SymlinkProvider) Health(base, accountDir string) error
  • func (p *SymlinkProvider) Kind() Kind
  • func (p *SymlinkProvider) Setup(base, accountDir string) error
  • func (p *SymlinkProvider) Sync(base, accountDir string) error
  • func (p *SymlinkProvider) Teardown(base, accountDir string) error

Variables

var ExcludedEntries = map[string]bool{
	"daemon": true,
	"ide":    true,
}

ExcludedEntries are top-level ~/.claude entries that must NOT be shared across accounts. Each excluded entry becomes a private, empty per-account directory instead.

• daemon: Claude Code's own PID-keyed worker supervisor (daemon/roster.json records a supervisorPid + worker registry). Sharing it makes two sessions fight over one supervisor.
• ide: per-process IDE lock/socket files; a pooled session must not advertise itself on acct-00's IDE registry.

Functions

func FuseBuilt

func FuseBuilt() bool

FuseBuilt reports whether this binary includes the fuse provider at all.

Types

type Kind

type Kind string

Kind identifies an overlay provider.

const (
	KindSymlink Kind = "symlink"
	KindFuse    Kind = "fuse"
)

func Detect

func Detect() Kind

Detect chooses the best overlay provider for this machine. It prefers fuse (a live mirror that auto-includes new entries) when the binary was built with -tags fuse AND a throwaway probe-mount via fuse-t succeeds — which also walks the user through the one-time "Network Volumes" privacy grant. Otherwise it falls back to the always-available symlink provider.

type Provider

type Provider interface {
	Kind() Kind

	// Setup makes accountDir reflect base. Idempotent.
	Setup(base, accountDir string) error

	// Sync re-asserts the overlay, picking up new top-level entries in base
	// and repairing drift. Idempotent. Safe to call repeatedly.
	Sync(base, accountDir string) error

	// Health returns nil if the overlay is intact, else a descriptive error.
	Health(base, accountDir string) error

	// Teardown removes the overlay from accountDir. It must never touch base.
	Teardown(base, accountDir string) error
}

Provider establishes and maintains an overlay of base at accountDir.

func For

func For(kind Kind) Provider

For returns the provider for a given kind. Unknown/empty kinds fall back to the symlink provider. The fuse provider is only returned when the binary was built with -tags fuse AND fuse-t is usable; otherwise this returns symlink.

type SymlinkProvider

type SymlinkProvider struct{}

SymlinkProvider symlinks every top-level entry of base into accountDir, except ExcludedEntries (which get private empty dirs) and skipEntries. New top-level entries that appear in base later are picked up by Sync.

func (*SymlinkProvider) Health

func (p *SymlinkProvider) Health(base, accountDir string) error

Health verifies every shared top-level entry of base is correctly linked in accountDir and every excluded entry is a real local dir.

func (*SymlinkProvider) Kind

func (p *SymlinkProvider) Kind() Kind

func (*SymlinkProvider) Setup

func (p *SymlinkProvider) Setup(base, accountDir string) error

Setup creates accountDir and asserts all links. Idempotent.

func (*SymlinkProvider) Sync

func (p *SymlinkProvider) Sync(base, accountDir string) error

Sync walks base's top-level entries and asserts the correct shape in accountDir: a symlink for shared entries, a private dir for excluded ones.

func (*SymlinkProvider) Teardown

func (p *SymlinkProvider) Teardown(base, accountDir string) error

Teardown removes the account dir's overlay. Because every shared entry is a symlink (removing it never touches base) and excluded entries are this account's own private dirs, the whole account dir can be removed. It refuses to operate on base as a guard against misuse.