session

Documentation

Index

• func DecodePath(dirName string) string
• func DefaultClaudeDir() string
• func EncodePath(fsPath string) string
• func ProjectNameFromDir(dir string) string
• func ScanNameFields(path string) (slug, customTitle string)
• type Discoverer
  • func (d *Discoverer) ListAllSessions() ([]Info, error)
  • func (d *Discoverer) ListProjects() ([]string, error)
  • func (d *Discoverer) ListSessions(projectDir string) ([]Info, error)
• type FindResult
  • func FindByID(claudeDir, id string) (*FindResult, error)
  • func FindSessionsForCWD(claudeDir, cwd string) []FindResult
• type Info
  • func (i Info) DisplayName() string
  • func (i Info) IsActive() bool
  • func (i Info) ShortID() string
• type MoveResult
  • func CopySession(claudeDir string, found *FindResult, targetPath string) (*MoveResult, error)
  • func MoveSession(claudeDir string, found *FindResult, targetPath string) (*MoveResult, error)
• type OrphanedProject
  • func FindOrphans(claudeDir string) ([]OrphanedProject, error)
• type QuickStats
• type RelocatePlan
  • func PlanRelocate(claudeDir, fromPath, toPath string) (*RelocatePlan, error)
• type RelocateResult
  • func Relocate(claudeDir, fromPath, toPath string, updateCWD bool) (*RelocateResult, error)

Functions

func DecodePath

func DecodePath(dirName string) string

DecodePath converts a Claude Code project directory name back to a filesystem path. -Users-name-dev-project → /Users/name/dev/project Note: this is ambiguous when directory names contain literal hyphens. Use ValidateDecodedPath to check if the result exists on disk.

func DefaultClaudeDir

func DefaultClaudeDir() string

DefaultClaudeDir returns the default ~/.claude path. In WSL2, if ~/.claude/projects doesn't exist, falls back to the Windows user's .claude directory at /mnt/c/Users/<name>/.claude.

func EncodePath

func EncodePath(fsPath string) string

EncodePath converts a filesystem path to Claude Code's project directory name. /Users/name/dev/project → -Users-name-dev-project

func ProjectNameFromDir

func ProjectNameFromDir(dir string) string

ProjectNameFromDir extracts a human-readable project name from a Claude project directory path.

func ScanNameFields

func ScanNameFields(path string) (slug, customTitle string)

ScanNameFields extracts slug and custom title from a JSONL file without full parsing. Exported for use in commands that need the display name.

Types

type Discoverer

type Discoverer struct {
	ClaudeDir string
}

Discoverer finds sessions across Claude project directories.

func (*Discoverer) ListAllSessions

func (d *Discoverer) ListAllSessions() ([]Info, error)

ListAllSessions returns sessions across all projects, sorted by modification time.

func (*Discoverer) ListProjects

func (d *Discoverer) ListProjects() ([]string, error)

ListProjects returns all project directory paths under the claude dir.

func (*Discoverer) ListSessions

func (d *Discoverer) ListSessions(projectDir string) ([]Info, error)

ListSessions returns sessions for a specific project directory.

type FindResult

type FindResult struct {
	SessionID   string // full UUID
	ProjectDir  string // encoded project directory name
	ProjectPath string // decoded filesystem path
	FullPath    string // full path to the JSONL file
	// contains filtered or unexported fields
}

FindResult holds the result of finding a session by ID.

func FindByID

func FindByID(claudeDir, id string) (*FindResult, error)

FindByID searches all project directories for a session matching the given full UUID, UUID prefix, slug, or custom title. Returns an error if not found or ambiguous.

func FindSessionsForCWD

func FindSessionsForCWD(claudeDir, cwd string) []FindResult

FindSessionsForCWD searches all projects for sessions whose project path contains the given directory name. Returns matches from projects OTHER than the exact CWD-encoded directory, to find "misplaced" sessions.

type Info

type Info struct {
	SessionID    string
	Slug         string
	CustomTitle  string // user-set session name (claude --name)
	FullPath     string
	FirstPrompt  string
	MessageCount int
	Created      time.Time
	Modified     time.Time
	GitBranch    string
	ProjectPath  string
	ProjectName  string
	FileSizeMB   float64
	IsSidechain  bool
	ContextStats *QuickStats
	Zombie       bool
	ZombieReason string
}

Info holds metadata about a single conversation session.

func (Info) DisplayName

func (i Info) DisplayName() string

DisplayName returns the custom title if set, then slug, then short ID.

func (Info) IsActive

func (i Info) IsActive() bool

IsActive returns true if the session was modified within the last 60 seconds.

func (Info) ShortID

func (i Info) ShortID() string

ShortID returns the first 8 characters of the session ID.

type MoveResult

type MoveResult struct {
	SessionID    string
	FromProject  string // decoded source path
	ToProject    string // decoded target path
	NewPath      string // new JSONL file path
	IndexUpdated bool
}

MoveResult holds the result of moving a session.

func CopySession

func CopySession(claudeDir string, found *FindResult, targetPath string) (*MoveResult, error)

CopySession copies a session JSONL file to the project directory for targetPath. The original file is preserved. Creates the target directory if it doesn't exist. Updates sessions-index.json in the target.

func MoveSession

func MoveSession(claudeDir string, found *FindResult, targetPath string) (*MoveResult, error)

MoveSession moves a single session JSONL file from its current project directory to the project directory for targetPath. Creates the target directory if it doesn't exist. Updates sessions-index.json in both dirs.

type OrphanedProject

type OrphanedProject struct {
	DirName       string // directory name under projects/
	DecodedPath   string // decoded filesystem path
	FullDirPath   string // full path to the project directory
	SessionCount  int    // number of JSONL files
	TotalMessages int    // total messages across all sessions
}

OrphanedProject represents a project directory whose decoded path no longer exists.

func FindOrphans

func FindOrphans(claudeDir string) ([]OrphanedProject, error)

FindOrphans scans all project directories and returns those whose decoded filesystem path no longer exists on disk.

type QuickStats

type QuickStats struct {
	ContextTokens        int
	ContextPct           float64
	ImageCount           int
	CompactionCount      int
	LastCompactionBefore int
	LastCompactionAfter  int
	EstimatedCost        float64
	Model                string
	SignalPercent        int     // 0-100, estimated signal/noise ratio
	ClientType           string  // "cli", "desktop", or "unknown"
	EntropyScore         float64 // 0-100
	EntropyLevel         string  // LOW/MEDIUM/HIGH/CRITICAL
	CleanupStatus        string  // clean/due/overdue
	CleanupCadenceScore  float64 // 0-100
}

QuickStats holds lightweight context stats for the session browser.

type RelocatePlan

type RelocatePlan struct {
	OldPath      string
	NewPath      string
	OldDirName   string
	NewDirName   string
	SessionCount int
	IndexEntries int
	OldDirExists bool
	NewDirExists bool
}

RelocatePlan describes what a relocation would do without executing it.

func PlanRelocate

func PlanRelocate(claudeDir, fromPath, toPath string) (*RelocatePlan, error)

PlanRelocate creates a dry-run plan for relocating sessions.

type RelocateResult

type RelocateResult struct {
	OldDirName    string
	NewDirName    string
	SessionsFound int
	IndexUpdated  bool
	CWDUpdated    int // entries with CWD rewritten
	DryRun        bool
}

RelocateResult holds the result of a session relocation operation.

func Relocate

func Relocate(claudeDir, fromPath, toPath string, updateCWD bool) (*RelocateResult, error)

Relocate moves sessions from one project path to another. This renames the project directory and updates sessions-index.json. If updateCWD is true, also rewrites CWD fields in JSONL entries.