Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-shared-claude-home-switch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Claude agents on hives with per-agent users no longer have to log out about every 8 hours: set `HIVE_SHARED_CLAUDE_HOME=1` to keep every agent's `~/.claude` as one whole-directory link to the shared `/data/home/.claude`, the layout from before [#17031](https://github.com/hivecommons/hive/issues/17031). Claude Code saves a refreshed token by renaming a file over `.credentials.json`; in a per-agent `~/.claude` that replaced the credential link, so the refresh never reached the shared login and the other agents were left on a rotated grant. With the directory linked, the refresh lands in the shared login. The switch is off by default. While it is on, Claude agents share `CLAUDE.md`, history, todos and memory again, a per-agent `.claude` is moved aside (never deleted) on the next launch, and `clear_on_kick` skips Claude. See `src/docs/agent-configuration.md`.
6 changes: 6 additions & 0 deletions src/crux/agent/claude_credential_bridge.go
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,12 @@ func preserveClaudeCredential(path string, now time.Time) (string, error) {
func (m *Manager) rebridgeClaudeCredential(agentName, link, target, trigger string) *claudeBridgeRepair {
rep, err := m.repairClaudeCredentialBridge(agentName, link, target)
if errors.Is(err, errClaudeBridgeLinkIsTarget) {
if sharedClaudeHomeForced() {
// The operator chose the whole-directory link
// (HIVE_SHARED_CLAUDE_HOME=1): the agent's credential path IS the
// shared login by design, so there is nothing to bridge or report.
return nil
}
// The legacy layout: skipped, and said once per agent rather than on
// every watchdog cycle. Not audited (nothing changed).
if _, seen := claudeBridgeLegacyWarned.LoadOrStore(link, true); !seen {
Expand Down
10 changes: 9 additions & 1 deletion src/crux/agent/cli_memory.go
Original file line number Diff line number Diff line change
Expand Up @@ -171,14 +171,22 @@ func (m *Manager) seedCopilotMemorySetting(agent *AgentProcess, home string) {
// agent might have run, under its own HOME and CODEX_HOME only. Shared-home
// paths are never returned: under HIVE_SHARED_AGENT_HOME=1 (or a UID-0
// agent) the stores are fleet-shared and wiping them for one agent's kick
// would erase every other agent's memory too.
// would erase every other agent's memory too. The same holds for one CLI home
// that is a whole-directory link to the shared home (HIVE_SHARED_CLAUDE_HOME=1).
func cliMemoryStorePaths(agent *AgentProcess, backend string) []string {
if agent.UID <= 0 || sharedAgentHomeForced() {
return nil
}
home := AgentHome(agent.Name, agent.UID, backend)
var paths []string
for _, spec := range perAgentCLIHomes {
// A CLI home that is a whole-directory link into the shared home
// (HIVE_SHARED_CLAUDE_HOME=1, or a legacy bridge not yet retired)
// holds the fleet's stores, not this agent's: a path through it
// would wipe every other agent's memory too.
if info, err := os.Lstat(filepath.Join(home, spec.dir)); err == nil && info.Mode()&os.ModeSymlink != 0 {
continue
}
for _, rel := range spec.memoryRel {
matches, err := filepath.Glob(filepath.Join(home, spec.dir, filepath.FromSlash(rel)))
if err != nil {
Expand Down
29 changes: 29 additions & 0 deletions src/crux/agent/cli_memory_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -213,3 +213,32 @@ func TestClearCLIMemoryForKick_OffByDefaultAndNeverSharedHome(t *testing.T) {
t.Errorf("uid 0 returned stores to wipe: %v", got)
}
}

// A ~/.claude that is a whole-directory link to the shared home
// (HIVE_SHARED_CLAUDE_HOME=1, or a legacy bridge) holds every agent's memory:
// the per-kick wipe must never be handed a path through it.
func TestCLIMemoryStorePaths_SkipsWholeDirectoryLink(t *testing.T) {
shared := withSharedAgentHome(t)
home := interactiveHomePath("scanner")
sharedMem := filepath.Join(shared, ".claude", "projects", "-data-agents-coder", "memory")
if err := os.MkdirAll(sharedMem, 0o755); err != nil {
t.Fatal(err)
}
if err := os.MkdirAll(home, 0o755); err != nil {
t.Fatal(err)
}
if err := os.Symlink(filepath.Join(shared, ".claude"), filepath.Join(home, ".claude")); err != nil {
t.Fatal(err)
}

on := &config.CLIMemoryConfig{ClearOnKick: true}
ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{CLIMemory: on}}
if got := cliMemoryStorePaths(ap, "claude"); len(got) != 0 {
t.Errorf("a whole-directory link returned shared stores to wipe: %v", got)
}
m := interactiveHomeTestManager(t)
m.clearCLIMemoryForKick(ap, "claude")
if _, err := os.Stat(sharedMem); err != nil {
t.Errorf("the shared memory store was wiped through the link: %v", err)
}
}
3 changes: 3 additions & 0 deletions src/crux/agent/interactive_home.go
Original file line number Diff line number Diff line change
Expand Up @@ -405,6 +405,9 @@ func (m *Manager) setupPerAgentCLIHomes(agentName, home string, uid int) {
}

func (m *Manager) setupPerAgentCLIHome(agentName, home string, uid int, spec perAgentCLIHome) {
if spec.dir == claudeHomeDirName && sharedClaudeHomeForced() && m.bridgeSharedClaudeHome(agentName, home) {
return
}
dir := filepath.Join(home, spec.dir)
shared := filepath.Join(sharedAgentHome, spec.dir)
if info, err := os.Lstat(dir); err == nil && info.Mode()&os.ModeSymlink != 0 {
Expand Down
112 changes: 112 additions & 0 deletions src/crux/agent/interactive_home_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -677,3 +677,115 @@ func TestSweepOrphanedClaudeTmp(t *testing.T) {
t.Errorf("real .claude.json must survive the sweep: %v", err)
}
}

// HIVE_SHARED_CLAUDE_HOME=1: ~/.claude becomes a whole-directory link to the
// shared Claude directory, so a credential the CLI renames into place lands in
// the shared login. The per-agent directory is moved aside, never deleted, and
// the other CLI homes stay per agent.
func TestSetupInteractiveHome_SharedClaudeHomeLinksWholeDirectory(t *testing.T) {
shared := withSharedAgentHome(t)
t.Setenv("HIVE_SHARED_CLAUDE_HOME", "1")
m := interactiveHomeTestManager(t)
ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}}
home := interactiveHomePath("scanner")
sharedClaude := filepath.Join(shared, ".claude")
if err := os.MkdirAll(sharedClaude, 0o755); err != nil {
t.Fatal(err)
}

// The per-agent layout: a real ~/.claude holding this agent's memory.
memRel := filepath.Join("projects", "-data-agents-scanner", "memory", "MEMORY.md")
mem := filepath.Join(home, ".claude", memRel)
if err := os.MkdirAll(filepath.Dir(mem), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(mem, []byte("# mine"), 0o644); err != nil {
t.Fatal(err)
}

m.setupInteractiveHome(ap, "claude")

link := filepath.Join(home, ".claude")
if target, err := os.Readlink(link); err != nil || target != sharedClaude {
t.Fatalf(".claude is not a link to the shared directory: target=%q err=%v", target, err)
}
// The per-agent directory was moved aside with its contents.
moved, err := filepath.Glob(filepath.Join(home, ".claude.per-agent-*", memRel))
if err != nil || len(moved) != 1 {
t.Fatalf("per-agent directory not preserved exactly once: %v err=%v", moved, err)
}
if data, err := os.ReadFile(moved[0]); err != nil || string(data) != "# mine" {
t.Errorf("moved-aside memory changed: %q err=%v", data, err)
}
// What the CLI does on a token refresh: a temp file in ~/.claude renamed
// over .credentials.json. Through the link it lands in the shared login.
tmp := filepath.Join(link, ".credentials.json.tmp")
if err := os.WriteFile(tmp, []byte(`{"claudeAiOauth":{}}`), 0o600); err != nil {
t.Fatal(err)
}
if err := os.Rename(tmp, filepath.Join(link, ".credentials.json")); err != nil {
t.Fatal(err)
}
if info, err := os.Lstat(filepath.Join(sharedClaude, ".credentials.json")); err != nil || !info.Mode().IsRegular() {
t.Errorf("refreshed credential did not land in the shared directory: info=%v err=%v", info, err)
}
if target, err := os.Readlink(link); err != nil || target != sharedClaude {
t.Errorf("the rename replaced the directory link: target=%q err=%v", target, err)
}
// The other CLI homes are still real per-agent directories.
if info, err := os.Lstat(filepath.Join(home, ".gemini")); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
t.Errorf(".gemini should stay a per-agent directory: info=%v err=%v", info, err)
}

// Idempotent: a second launch keeps the link and moves nothing else.
m.setupInteractiveHome(ap, "claude")
if target, err := os.Readlink(link); err != nil || target != sharedClaude {
t.Errorf(".claude link lost on re-provision: target=%q err=%v", target, err)
}
if asides, _ := filepath.Glob(filepath.Join(home, ".claude.per-agent-*")); len(asides) != 1 {
t.Errorf("re-provision moved something aside again: %v", asides)
}
}

// With no shared Claude directory to link to, the switch keeps the per-agent
// directory: a dangling directory link would break the CLI's own mkdir -p.
func TestSetupInteractiveHome_SharedClaudeHomeNeedsSharedDirectory(t *testing.T) {
withSharedAgentHome(t)
t.Setenv("HIVE_SHARED_CLAUDE_HOME", "1")
m := interactiveHomeTestManager(t)
ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}}
home := interactiveHomePath("scanner")

m.setupInteractiveHome(ap, "claude")

if info, err := os.Lstat(filepath.Join(home, ".claude")); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
t.Errorf(".claude should be a per-agent directory when the shared one is missing: info=%v err=%v", info, err)
}
}

// Turning the switch off again goes back to the per-agent layout on the next
// launch: the directory link is retired like any legacy bridge.
func TestSetupInteractiveHome_SharedClaudeHomeOffRetiresLink(t *testing.T) {
shared := withSharedAgentHome(t)
m := interactiveHomeTestManager(t)
ap := &AgentProcess{Name: "scanner", UID: 1001, Config: config.AgentConfig{Backend: "claude"}}
home := interactiveHomePath("scanner")
if err := os.MkdirAll(filepath.Join(shared, ".claude"), 0o755); err != nil {
t.Fatal(err)
}

t.Setenv("HIVE_SHARED_CLAUDE_HOME", "1")
m.setupInteractiveHome(ap, "claude")
if info, err := os.Lstat(filepath.Join(home, ".claude")); err != nil || info.Mode()&os.ModeSymlink == 0 {
t.Fatalf(".claude should be a link while the switch is on: info=%v err=%v", info, err)
}

t.Setenv("HIVE_SHARED_CLAUDE_HOME", "")
m.setupInteractiveHome(ap, "claude")
if info, err := os.Lstat(filepath.Join(home, ".claude")); err != nil || info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {
t.Errorf(".claude should be a per-agent directory again: info=%v err=%v", info, err)
}
if target, err := os.Readlink(filepath.Join(home, ".claude", ".credentials.json")); err != nil || target != filepath.Join(shared, ".claude", ".credentials.json") {
t.Errorf(".credentials.json bridge not restored: target=%q err=%v", target, err)
}
}
129 changes: 129 additions & 0 deletions src/crux/agent/shared_claude_home.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
package agent

import (
"fmt"
"os"
"path/filepath"
"time"
)

// sharedClaudeHomeForced reports whether the operator asked for every agent's
// ~/.claude to stay ONE whole-directory link to the shared /data/home/.claude
// (HIVE_SHARED_CLAUDE_HOME=1), the layout from before hivecommons/hive#17031.
//
// It exists for the Claude login. Claude Code saves a refreshed OAuth token by
// renaming a temp file over .credentials.json. In a per-agent ~/.claude that
// rename replaces the credential link with a private file, so the refresh
// (which also rotates the grant) never reaches the shared login and the rest
// of the fleet is left on a dead one. With the whole directory linked, the
// rename happens inside the shared directory and every agent reads the new
// token, exactly as before #17031. The price is that Claude agents share one
// CLAUDE.md, history.jsonl and todos/ again, and can read each other's
// transcripts and auto-memory.
func sharedClaudeHomeForced() bool {
return os.Getenv("HIVE_SHARED_CLAUDE_HOME") == "1"
}

// claudeHomeAsideInfix names a per-agent ~/.claude that bridgeSharedClaudeHome
// moved aside: <home>/.claude.per-agent-<UTC timestamp>.
const claudeHomeAsideInfix = ".per-agent-"

// bridgeSharedClaudeHome makes $HOME/.claude a whole-directory link to the
// shared /data/home/.claude (HIVE_SHARED_CLAUDE_HOME=1, see
// sharedClaudeHomeForced). It reports whether the link is in place; on false
// the caller provisions the per-agent directory as usual, so a home this
// cannot convert is never left without a .claude.
//
// A per-agent directory found at the path is moved aside to
// .claude.per-agent-<UTC timestamp> in the same home, never deleted: it holds
// the agent's transcripts and auto-memory from the per-agent layout. Nothing
// under the shared tree is touched. A link is only created when the shared
// directory exists, because the CLI's own mkdir -p fails through a dangling
// directory link.
func (m *Manager) bridgeSharedClaudeHome(agentName, home string) bool {
dir := filepath.Join(home, claudeHomeDirName)
shared := filepath.Join(sharedAgentHome, claudeHomeDirName)
if info, err := os.Stat(shared); err != nil || !info.IsDir() {
m.logger.Warn("HIVE_SHARED_CLAUDE_HOME=1 but the shared Claude directory is missing; keeping the per-agent directory",
"agent", agentName, "shared", shared, "error", err)
return false
}
aside := ""
info, err := os.Lstat(dir)
switch {
case err == nil && info.Mode()&os.ModeSymlink != 0:
if existing, rerr := os.Readlink(dir); rerr == nil && existing == shared {
return true
}
if rerr := os.Remove(dir); rerr != nil {
m.logger.Warn("HIVE_SHARED_CLAUDE_HOME=1 but a stale .claude link could not be replaced",
"agent", agentName, "link", dir, "error", rerr)
return false
}
case err == nil && info.IsDir():
moved, rerr := moveAsidePerAgentClaudeHome(dir, claudeBridgeNow())
if rerr != nil {
m.logger.Warn("HIVE_SHARED_CLAUDE_HOME=1 but the per-agent Claude directory could not be moved aside; keeping it",
"agent", agentName, "dir", dir, "error", rerr)
return false
}
aside = moved
case err == nil:
m.logger.Warn("HIVE_SHARED_CLAUDE_HOME=1 but .claude is neither a directory nor a link; leaving it",
"agent", agentName, "path", dir)
return false
case !os.IsNotExist(err):
m.logger.Warn("HIVE_SHARED_CLAUDE_HOME=1 but .claude could not be inspected",
"agent", agentName, "path", dir, "error", err)
return false
}
if err := os.Symlink(shared, dir); err != nil {
if existing, rerr := os.Readlink(dir); rerr == nil && existing == shared {
// Another launch of the same agent linked it first.
return true
}
m.logger.Warn("HIVE_SHARED_CLAUDE_HOME=1 but the shared Claude directory could not be linked",
"agent", agentName, "link", dir, "shared", shared, "error", err)
if aside != "" {
// Put the per-agent directory back so the agent is not left
// without a .claude.
if rerr := os.Rename(aside, dir); rerr != nil {
m.logger.Error("the per-agent Claude directory could not be put back",
"agent", agentName, "from", aside, "to", dir, "error", rerr)
}
}
return false
}
if aside != "" {
m.logger.Info("linked ~/.claude to the shared Claude directory (HIVE_SHARED_CLAUDE_HOME=1); the per-agent directory was moved aside, not deleted",
"agent", agentName, "link", dir, "shared", shared, "moved_to", aside)
} else {
m.logger.Info("linked ~/.claude to the shared Claude directory (HIVE_SHARED_CLAUDE_HOME=1)",
"agent", agentName, "link", dir, "shared", shared)
}
return true
}

// moveAsidePerAgentClaudeHome renames dir to a unique
// <dir>.per-agent-<UTC timestamp> beside it and returns the new path.
func moveAsidePerAgentClaudeHome(dir string, now time.Time) (string, error) {
base := dir + claudeHomeAsideInfix + now.UTC().Format("20060102T150405Z")
for i := 0; i < 100; i++ {
dst := base
if i > 0 {
dst = fmt.Sprintf("%s-%d", base, i)
}
_, err := os.Lstat(dst)
if err == nil {
continue
}
if !os.IsNotExist(err) {
return "", err
}
if err := os.Rename(dir, dst); err != nil {
return "", err
}
return dst, nil
}
return "", fmt.Errorf("no free name to move %s aside", dir)
}
15 changes: 15 additions & 0 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -705,6 +705,21 @@ Each repair writes a `claude_credential_rebridged` Audit Log entry naming the ag

The repair skips an agent whose whole `~/.claude` is still the old directory symlink to `/data/home/.claude`. That happens to an agent that has been paused or stopped since before the per-agent split, because only a launch replaces the directory link. Through that link the agent's `.credentials.json` is the shared login itself, so there is nothing private to move aside. The hive log says so once per agent (`claude credential bridge: this agent's .claude directory resolves to the shared login directory`), the card does not show a broken bridge, and the agent's next launch replaces the directory link with its own `~/.claude`.

#### Keeping one shared Claude directory

Set `HIVE_SHARED_CLAUDE_HOME=1` in the hive's environment to keep every agent's `~/.claude` as one whole-directory link to the shared `/data/home/.claude`, the layout from before [#17031](https://github.com/hivecommons/hive/issues/17031).

Use it when a hive with per-agent users signs in to Claude from the dashboard and its agents log out again about every 8 hours. With the whole directory linked, the CLI's refresh (a temp file renamed over `.credentials.json`) lands in the shared directory, so every agent reads the new token and the credential link is never replaced.

What changes while it is on:

- On an agent's next launch its `~/.claude` becomes the link. A per-agent `.claude` directory found there is moved aside to `~/.claude.per-agent-<UTC timestamp>`, never deleted.
- Claude agents share one `CLAUDE.md`, `history.jsonl` and `todos/` again, and can read each other's transcripts and auto-memory. This gives up the isolation #17031 added, for Claude only. `.gemini`, `.bob` and `.copilot` stay per agent.
- `agents.cli_memory.clear_on_kick` skips Claude, because the memory store is no longer the agent's own.
- Claude sessions recorded in the moved-aside directories are no longer scanned for the dashboard's token totals.

Unset the variable to go back: the next launch retires the link and creates a fresh per-agent directory. The moved-aside directory is left for you to restore by hand.

### CLI auto-memory (`agents.cli_memory`)

Subscription CLIs keep their own long-lived "memory" next to the transcripts: Claude Code's auto-memory (`~/.claude/projects/-data-agents-<name>/memory/MEMORY.md`), Codex memories (`$CODEX_HOME/memories/`), Copilot CLI's `memory` setting, and Gemini's `~/.gemini/GEMINI.md`. Hive agents already get their durable context from beads, the knowledge store, and the kick prompt, so a hidden per-CLI notebook mostly accumulates stale one-off inferences ([#17032](https://github.com/hivecommons/hive/issues/17032)). The `agents.cli_memory` block controls it fleet-wide, and each agent may override it with its own `cli_memory:` block:
Expand Down
4 changes: 4 additions & 0 deletions src/docs/agent-knowledge-and-memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,10 @@ conversation. `/clear` empties the chat; it does not touch anything on disk.
deleted — a pre-isolation `projects/*/memory` store is logged once for review.
The full table is in [agent-configuration.md](agent-configuration.md#per-agent-homes-what-is-shared-and-what-is-private).
- `HIVE_SHARED_AGENT_HOME=1` forces the legacy single shared home for all.
- `HIVE_SHARED_CLAUDE_HOME=1` keeps only `~/.claude` shared, as one
whole-directory link: Claude agents share `CLAUDE.md`, history, todos and
memory again, in exchange for a token refresh that reaches every agent. See
[agent-configuration.md](agent-configuration.md#keeping-one-shared-claude-directory).
- Inference (API-routed) agents use throwaway homes under
`/tmp/.claude-inference-home-<name>` that vanish with the pod.
- Contributor containers stage only `.credentials.json` and `settings.json`
Expand Down
Loading
Loading