breadcrumb

Documentation

Overview

Package breadcrumb manages permission-waiting breadcrumb files.

When Claude Code's PermissionRequest hook fires, the hook handler writes a small file to ~/.config/vitals/waiting/{session_id}. The statusline gather stage scans this directory to detect other sessions blocked on permission approval. PostToolUse and Stop hooks remove the breadcrumb.

Breadcrumbs older than staleTTL are ignored (covers hard-crash scenarios where neither PostToolUse nor Stop fires).

Index

• Variables
• func Remove(sessionID string) error
• func Write(b Breadcrumb) error
• type Breadcrumb
  • func FindWaiting(ownSessionID string) *Breadcrumb

Variables

var WaitingDir = func() string {
	home, err := os.UserHomeDir()
	if err != nil {
		return filepath.Join(os.TempDir(), "vitals", "waiting")
	}
	return filepath.Join(home, ".config", "vitals", "waiting")
}

WaitingDir returns the directory where breadcrumb files are stored. It is a variable so tests can redirect to a temp directory.

Functions

func Remove

func Remove(sessionID string) error

Remove deletes the breadcrumb for a session. Returns nil if the file does not exist (removal is idempotent).

func Write

func Write(b Breadcrumb) error

Write atomically creates a breadcrumb file for the given session. Uses temp-file + rename to avoid partial reads by the scanner.

Types

type Breadcrumb

type Breadcrumb struct {
	SessionID string `json:"session_id"`
	Project   string `json:"project"` // last path component of CWD
	ToolName  string `json:"tool_name,omitempty"`
}

Breadcrumb represents a permission-waiting marker for a Claude Code session.

func FindWaiting

func FindWaiting(ownSessionID string) *Breadcrumb

FindWaiting scans the breadcrumb directory for a non-stale breadcrumb from a session other than ownSessionID. Returns the first match, or nil if none.