paths

Documentation

Overview

Package paths holds transcript-directory discovery: the projects root, cwd→project-dir resolution (by matching the cwd recorded inside transcripts), contained-JSONL enumeration with symlink-out containment, and session-id resolution.

Index

• func AllProjectDirs() []string
• func CatalogDir() string
• func ConfigDir() string
• func ContainedJSONL(transcriptDir string) []string
• func DirCWD(tdir string) string
• func FileCWD(jsonlPath string) string
• func FindTranscriptDir(cwd string) string
• func FindTranscriptDirExplicit(dir string) string
• func ProjectCWD(tdir string) string
• func ProjectDirOf(jsonlPath string) string
• func ProjectLabel(tdir string) string
• func ProjectsRoot() string
• func TranscriptsRoot() string
• func WriteCatalogEntry(catalogDir string, entry CatalogEntry) error
• type CatalogEntry
  • func ReadCatalogEntry(path string) (CatalogEntry, error)
• type SessionHit
  • func ResolveSession(prefix string) []SessionHit

Functions

func AllProjectDirs

func AllProjectDirs() []string

AllProjectDirs returns every project dir under the projects root that holds at least one top-level *.jsonl.

func CatalogDir

func CatalogDir() string

CatalogDir is the durable home for rawclaw's session catalog: one flat directory under the rawclaw data home holding one entry per session id written at session birth. Honors $RAWCLAW_CATALOG_DIR if set, else $XDG_DATA_HOME/rawclaw/catalog (or ~/.local/share/rawclaw/catalog).

func ConfigDir

func ConfigDir() string

ConfigDir returns the Claude Code config dir: $CLAUDE_CONFIG_DIR if set, else ~/.claude. Unlike ProjectsRoot, this never requires the dir to already exist — a writer (e.g. `rawclaw setup`, which creates settings.json and the hooks dir on a fresh machine) needs the resolved path before anything is on disk yet.

func ContainedJSONL

func ContainedJSONL(transcriptDir string) []string

ContainedJSONL returns the recursive *.jsonl under transcriptDir, EXCLUDING any whose realpath escapes the root (symlink-out containment).

func DirCWD

func DirCWD(tdir string) string

DirCWD returns the working directory this project dir's transcripts record, or "" when none does. It samples ONE top-level transcript because a project dir maps 1:1 to a working directory by construction — the dir's name IS that path, encoded — so one sample answers for every session in the dir.

Unlike ProjectCWD it never substitutes the directory's own name for a real path: a caller storing a cwd needs to tell "the sessions here ran in /x/y" apart from "nothing here records where it ran."

func FileCWD

func FileCWD(jsonlPath string) string

FileCWD returns the working directory a single transcript file records, or "" when the file is unreadable or records none. It is firstCWD's exported form: the scope helpers above answer "what cwd does this PROJECT DIR have", while a per-session backfill needs the cwd of one named file.

func FindTranscriptDir

func FindTranscriptDir(cwd string) string

FindTranscriptDir resolves the projects subdir for `cwd` by matching the cwd recorded inside transcripts (authoritative), falling back to path encoding. Returns "" if none found.

Discovery is location-based only: the known projects root and the cwds its transcripts record. A directory that merely holds loose *.jsonl files is NOT treated as a transcripts dir here — that fallback once let a bare run from a folder like /tmp index the folder itself into the cache. Arbitrary-folder indexing is the explicit --dir opt-in: FindTranscriptDirExplicit.

func FindTranscriptDirExplicit

func FindTranscriptDirExplicit(dir string) string

FindTranscriptDirExplicit resolves `dir` like FindTranscriptDir, additionally accepting ANY directory that directly holds *.jsonl files. This is the explicit --dir opt-in for indexing an arbitrary transcript folder; the ordinary resolution runs first, so a working dir that happens to carry stray .jsonl data files still resolves to its recorded transcripts dir.

func ProjectCWD

func ProjectCWD(tdir string) string

ProjectCWD returns the working directory recorded in this project's transcripts (for path filtering), falling back to the encoded dir name.

func ProjectDirOf

func ProjectDirOf(jsonlPath string) string

ProjectDirOf returns the project dir a transcript file belongs to: the ancestor sitting directly under the projects root. Returns "" when the file is not under the projects root at all (an explicit --dir scope, or a source that shards by date rather than by project).

The file's own parent directory is NOT the answer in general: subagent and workflow transcripts live in SUBDIRECTORIES of their project dir, so reading the parent labels them "subagents" or "wf_<id>" instead of the project they actually ran in. Resolution is lexical, so it still answers for a transcript that has since been purged from disk.

func ProjectLabel

func ProjectLabel(tdir string) string

ProjectLabel returns a friendly project name = basename of the cwd recorded in a transcript, else the encoded dir basename.

func ProjectsRoot

func ProjectsRoot() string

ProjectsRoot returns the Claude Code projects root: $CLAUDE_CONFIG_DIR/projects if it exists, else ~/.claude/projects.

func TranscriptsRoot

func TranscriptsRoot() string

TranscriptsRoot is the durable home for rawclaw's OWN copy of every session it indexes — the transcript vault. It lives in the XDG DATA dir, NOT the disposable cache (which holds only rebuildable index dbs), because the vault is the truth the dbs are rebuilt FROM: deleting the cache must cost nothing. $XDG_DATA_HOME/rawclaw/transcripts, else ~/.local/share/rawclaw/transcripts. A vault file's mtime records when rawclaw last snapshotted that session, NOT when the session was last active: freshness comes from the live sources, which are re-indexed on every invoke.

func WriteCatalogEntry

func WriteCatalogEntry(catalogDir string, entry CatalogEntry) error

WriteCatalogEntry writes a catalog entry to dir/<session_id> atomically.

Types

type CatalogEntry

type CatalogEntry struct {
	SessionID      string `json:"session_id"`
	TranscriptPath string `json:"transcript_path,omitempty"`
	CWD            string `json:"cwd,omitempty"`
	Source         string `json:"source,omitempty"`
}

CatalogEntry is one entry in the durable session catalog.

func ReadCatalogEntry

func ReadCatalogEntry(path string) (CatalogEntry, error)

ReadCatalogEntry reads and parses a catalog entry from disk. Readers must tolerate unparseable entries (which serve as pure dedup markers).

type SessionHit

type SessionHit struct {
	SessionID string // full session id (the .jsonl stem == claude --resume id)
	Path      string // backing transcript file path
	CWD       string // working dir recorded in the transcript (may be "")
	Project   string // friendly project label
}

SessionHit is one result of ResolveSession: a top-level session whose id starts with the requested prefix. It carries the full session id, the working dir recorded in the transcript, and a friendly project label.

func ResolveSession

func ResolveSession(prefix string) []SessionHit

ResolveSession finds the TOP-LEVEL session(s) whose id starts with `prefix` (the 8-char label printed in search output). Subagent threads are skipped. It checks the durable session catalog first for O(1) direct or flat-dir prefix resolution, falling back to project-dir stem resolution if the catalog misses.