discovery

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const LiveTTL = time.Second

LiveTTL is how long LiveCache serves one read of the registry.

Variables

View Source
var GetParentPID = getParentPIDImpl

GetParentPID returns the parent PID for a given process, or 0 on error. Exported for use by the correlator. Variable so tests can override it.

View Source
var ProcessStartTime = ReadProcessStartTime

ProcessStartTime returns when a process started, or the zero time if unknown. It is a variable so tests can override it. Only IsLiveHolder uses it, and nothing outside tests calls that: both are kept as the pinned reference for LiveCache's rule. LiveCache checks start times with one batched ps of its own, so overriding this hook does not reach it.

Functions

func FindSessionFile

func FindSessionFile(sessionID, projectsDir string) string

FindSessionFile searches for a session JSONL file matching the given session ID within the projects directory. A found path is remembered (a session's file does not move) and only stat'ed on later calls; the search reads every project directory, and there are thousands.

func FindSessionFileAt added in v0.14.0

func FindSessionFileAt(sessionID, cwd, projectsDir string) string

FindSessionFileAt is FindSessionFile for a session believed to belong to cwd: it first checks that directory's project folder, one stat, and searches all of them only when the file is not there.

func FindSessionFileDefault

func FindSessionFileDefault(sessionID string) string

FindSessionFileDefault searches for a session file using the default ~/.claude/projects/ directory.

func GetProcessCwd

func GetProcessCwd(pid int) (string, error)

GetProcessCwd returns the current working directory of a process. Uses `lsof -a -d cwd -p PID -Fn` which only queries the cwd file descriptor instead of listing all open files. Times out after 3 seconds to avoid blocking the discovery loop when lsof hangs on a process.

func GetProcessCwds added in v0.14.0

func GetProcessCwds(pids []int) map[int]string

GetProcessCwds is GetProcessCwd for many processes with one lsof: the processes it cannot read (gone, not ours) are left out, as GetProcessCwd would fail for them.

func IsLiveHolder added in v0.14.0

func IsLiveHolder(e ClaudeRegistryEntry) bool

IsLiveHolder reports whether the registry entry's process is still the one that wrote it: the PID is alive and, when both start times are known, it started when the entry says. A stale entry whose PID was reused by an unrelated process does not count. No production caller: it is kept as the pinned reference for the rule LiveCache applies to every entry at once (liveHolders; TestLiveHolders_SameRuleAsIsLiveHolder).

func MatchTmuxSession

func MatchTmuxSession(sessions []TmuxSession, workingDir string) string

MatchTmuxSession finds a tmux session matching the "claude-<project>" naming convention based on the working directory's base name.

func MatchTmuxSessionByPID added in v0.11.0

func MatchTmuxSessionByPID(sessions []TmuxSession, pid int) string

MatchTmuxSessionByPID finds an aimux-prefixed tmux session whose pane contains the given PID. Falls back to this when MatchTmuxSession fails because the process CWD changed after launch.

func ProjectDirKey added in v0.14.0

func ProjectDirKey(cwd string) string

ProjectDirKey is the name Claude Code gives a working directory's folder under ~/.claude/projects: every character other than an ASCII letter or digit becomes "-". "" for no directory.

func PsLines added in v0.8.1

func PsLines(psOutput string) []string

PsLines returns the trimmed non-empty lines from ps aux output (skipping header). Providers use this to avoid re-splitting the shared snapshot.

func ReadClaudeRegistry added in v0.14.0

func ReadClaudeRegistry(dir string) map[int]ClaudeRegistryEntry

ReadClaudeRegistry returns registry entries keyed by PID. Unreadable or malformed files and entries without a PID or session ID are skipped, and a missing directory yields an empty map: the registry is an accuracy improvement, never a requirement.

func ReadClaudeRegistryStrict added in v0.14.0

func ReadClaudeRegistryStrict(dir string) (map[int]ClaudeRegistryEntry, error)

ReadClaudeRegistryStrict is ReadClaudeRegistry for decisions that must not guess: any registry file it cannot read or decode is an error, since that file may be the live terminal holding a session.

func ReadProcessStartTime added in v0.14.0

func ReadProcessStartTime(pid int) time.Time

ReadProcessStartTime asks ps for pid's start time (UTC), or the zero time on any failure. The one `ps -o lstart=` reader; provider uses it too.

func ScanProcesses

func ScanProcesses() ([]agent.Agent, error)

ScanProcesses runs `ps aux`, parses each line, and returns Instance stubs for every detected Claude process. Subagent processes (whose parent PID is also a Claude process) are automatically filtered out so that only top-level sessions appear.

func ScanProcessesFromOutput added in v0.8.1

func ScanProcessesFromOutput(psOutput string) []agent.Agent

ScanProcessesFromOutput parses pre-captured `ps aux` output for Claude processes.

func SessionFilesForDir

func SessionFilesForDir(workingDir string) []string

SessionFilesForDir finds all JSONL session files associated with a working directory. Claude converts directory paths by replacing "/" with "-" to form the project directory key.

func ValidSessionID added in v0.14.0

func ValidSessionID(id string) bool

ValidSessionID reports whether id looks like an agent session id (letters, digits, dash, underscore). Anything else, such as a path separator, ".." or a glob character, is refused before it reaches the filesystem.

Types

type AgentProvider

type AgentProvider interface {
	Name() string
	Discover() ([]agent.Agent, error)
}

AgentProvider is the minimal interface that the orchestrator requires from each provider. It is intentionally kept small to avoid a circular dependency between the discovery and provider packages. Any type implementing provider.Provider automatically satisfies this interface.

type ClaudeRegistryEntry added in v0.14.0

type ClaudeRegistryEntry struct {
	PID       int    `json:"pid"`
	SessionID string `json:"sessionId"`
	CWD       string `json:"cwd"`
	Status    string `json:"status"`    // "idle" or "busy" in observed files
	ProcStart string `json:"procStart"` // process start, UTC, ctime format
}

ClaudeRegistryEntry is one running Claude Code session as recorded by Claude Code itself in ~/.claude/sessions/<pid>.json. The format is not documented, so only the fields aimux needs are read and every field is treated as optional.

func (ClaudeRegistryEntry) StartedAt added in v0.14.0

func (e ClaudeRegistryEntry) StartedAt() (time.Time, bool)

StartedAt parses ProcStart. It reports false when the value is missing or in an unexpected format, so callers can skip the PID-reuse check.

type LiveCache added in v0.14.0

type LiveCache struct {
	Dir string        // ~/.claude/sessions
	TTL time.Duration // 0: read on every call
	// CommandLines lists processes as `ps -axo pid=,args=` prints them, for
	// Strict reads. Nil: run that ps. Set it to test with canned output.
	CommandLines func() ([]byte, error)
	// contains filtered or unexported fields
}

LiveCache is Claude Code's harness.LiveSessions, both modes over one read (the table on harness.Mode): the registry entries (readClaudeRegistry) whose process is still the one that wrote them, by IsLiveHolder's rule, and for Strict also the live claude processes that name a session on their command line (claude.CommandLineSessions) and have no live entry of their own. A List read serves every List caller for TTL, concurrent callers during a read wait for that read, and a read checks every start time with one ps run instead of one per entry. A Strict read is never served from the cache: it takes only a read that began after the call (a running one if it started later, else one of its own), since a send must see a terminal opened a moment ago or two processes write one session. Strict callers arriving together still share one read. The command lines (one `ps -axo`) are read only by a Strict read; a List read never reads them, and a Strict read serves List callers for TTL. Safe for concurrent use.

func NewLiveCache added in v0.14.0

func NewLiveCache(dir string, ttl time.Duration) *LiveCache

NewLiveCache reads the registry in dir, serving each read for ttl.

func (*LiveCache) Holders added in v0.14.0

func (c *LiveCache) Holders(mode harness.Mode) ([]harness.Holder, error)

Holders returns every live holder by mode's rule, in a slice of the caller's own. A List read never fails; a Strict read fails when the registry could not be fully read.

func (*LiveCache) Registry added in v0.14.0

func (c *LiveCache) Registry() map[int]ClaudeRegistryEntry

Registry is every entry of the registry read List would serve now (ReadClaudeRegistry's answer, from the same cached read), in a map of the caller's own: Claude's discovery reads it, so a refresh that also asks for holders reads the registry and runs ps once.

type Orchestrator

type Orchestrator struct {
	// contains filtered or unexported fields
}

Orchestrator coordinates multiple providers and environments to produce a unified list of agents.

func NewOrchestrator

func NewOrchestrator(providers ...AgentProvider) *Orchestrator

NewOrchestrator creates an orchestrator that iterates the given providers.

func (*Orchestrator) AddEnvironment added in v0.13.0

func (o *Orchestrator) AddEnvironment(env environment.Environment)

AddEnvironment registers an environment for remote agent discovery.

func (*Orchestrator) Discover

func (o *Orchestrator) Discover() ([]agent.Agent, error)

Discover queries every registered provider and merges the results. A single process snapshot is taken first and shared with providers that implement SnapshotProvider, avoiding redundant ps/tmux calls.

func (*Orchestrator) ProviderFor

func (o *Orchestrator) ProviderFor(name string) AgentProvider

ProviderFor returns the first provider whose Name() matches the given name, or nil if no provider matches.

type ProcFacts added in v0.14.0

type ProcFacts struct {
	PPID  int
	Start time.Time // UTC, second precision as ps reports it
}

ProcFacts are what discovery asks ps about a process besides ps aux: its parent (the subagent walk) and its start time (registry checks and session matching).

type SessionInfo

type SessionInfo struct {
	SessionID        string
	GitBranch        string
	Model            string
	TokensIn         int64
	TokensOut        int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	MessageCount     int
	LastTimestamp    time.Time
	LastAction       string // most recent tool call, e.g. "Ed main.go"
}

SessionInfo holds aggregated data parsed from a Claude JSONL session file.

func ParseSessionFile

func ParseSessionFile(path string) (SessionInfo, error)

ParseSessionFile reads a JSONL session file and aggregates token usage across all messages. Live transcripts reach hundreds of MB and discovery asks every few seconds, so it remembers what it parsed per file and reads only what was appended since: an unchanged file (size and mtime) is not read at all, a file that shrank or was replaced is read from the start. The result is always that of a parse of the whole file.

type Snapshot added in v0.8.1

type Snapshot struct {
	PsOutput     string            // raw `ps aux` output
	TmuxSessions []TmuxSession     // parsed tmux sessions
	Procs        map[int]ProcFacts // every process's parent and start; nil if ps failed
}

Snapshot holds shared data collected once and reused by all providers.

func TakeSnapshot added in v0.8.1

func TakeSnapshot() *Snapshot

TakeSnapshot captures a process snapshot (ps aux, parents and start times, tmux) in parallel.

func (*Snapshot) ParentPID added in v0.14.0

func (s *Snapshot) ParentPID(pid int) int

ParentPID is GetParentPID from the snapshot; a process it does not have (started since, or no snapshot) is asked of ps as before.

func (*Snapshot) StartTime added in v0.14.0

func (s *Snapshot) StartTime(pid int) (time.Time, bool)

StartTime is the process's start time from the snapshot; false when the snapshot does not have it.

type SnapshotProvider added in v0.8.1

type SnapshotProvider interface {
	DiscoverWithSnapshot(snap *Snapshot) ([]agent.Agent, error)
}

SnapshotProvider is an optional interface for providers that can accept a shared process snapshot. This avoids each provider calling `ps aux` and `tmux list-sessions` independently (~200ms each).

type TmuxSession

type TmuxSession struct {
	Name     string
	Attached bool
}

TmuxSession represents a tmux session with its name and attachment state.

func ListTmuxSessions

func ListTmuxSessions() []TmuxSession

ListTmuxSessions runs `tmux list-sessions` and returns the parsed results. Returns nil if tmux is not running or not installed.

type Watcher added in v0.9.0

type Watcher struct {
	// contains filtered or unexported fields
}

Watcher monitors session directories for new files and triggers a callback. Events are debounced to avoid excessive re-discovery on rapid file creation.

func NewWatcher added in v0.9.0

func NewWatcher(dirs []string, onChange func()) (*Watcher, error)

NewWatcher creates a watcher on the given directories. Directories that don't exist are silently skipped. The onChange callback is debounced to fire at most once per 500ms.

func (*Watcher) Stop added in v0.9.0

func (w *Watcher) Stop()

Stop shuts down the watcher.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL