Documentation
¶
Index ¶
- Constants
- Variables
- func FindSessionFile(sessionID, projectsDir string) string
- func FindSessionFileAt(sessionID, cwd, projectsDir string) string
- func FindSessionFileDefault(sessionID string) string
- func GetProcessCwd(pid int) (string, error)
- func GetProcessCwds(pids []int) map[int]string
- func IsLiveHolder(e ClaudeRegistryEntry) bool
- func MatchTmuxSession(sessions []TmuxSession, workingDir string) string
- func MatchTmuxSessionByPID(sessions []TmuxSession, pid int) string
- func ProjectDirKey(cwd string) string
- func PsLines(psOutput string) []string
- func ReadClaudeRegistry(dir string) map[int]ClaudeRegistryEntry
- func ReadClaudeRegistryStrict(dir string) (map[int]ClaudeRegistryEntry, error)
- func ReadProcessStartTime(pid int) time.Time
- func ScanProcesses() ([]agent.Agent, error)
- func ScanProcessesFromOutput(psOutput string) []agent.Agent
- func SessionFilesForDir(workingDir string) []string
- func ValidSessionID(id string) bool
- type AgentProvider
- type ClaudeRegistryEntry
- type LiveCache
- type Orchestrator
- type ProcFacts
- type SessionInfo
- type Snapshot
- type SnapshotProvider
- type TmuxSession
- type Watcher
Constants ¶
const LiveTTL = time.Second
LiveTTL is how long LiveCache serves one read of the registry.
Variables ¶
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.
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 ¶
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
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 ¶
FindSessionFileDefault searches for a session file using the default ~/.claude/projects/ directory.
func GetProcessCwd ¶
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
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
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
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
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 ¶
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
ScanProcessesFromOutput parses pre-captured `ps aux` output for Claude processes.
func SessionFilesForDir ¶
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
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 ¶
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.
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
NewLiveCache reads the registry in dir, serving each read for ttl.
func (*LiveCache) Holders ¶ added in v0.14.0
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
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.
type SnapshotProvider ¶ added in v0.8.1
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 ¶
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
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.