Documentation
¶
Index ¶
- func FormatHealth(sh SystemHealth) string
- func KillLocalAgent(a agent.Agent) error
- type Claude
- func (c *Claude) CanEmbed() bool
- func (c *Claude) Discover() ([]agent.Agent, error)
- func (c *Claude) DiscoverWithSnapshot(snap *discovery.Snapshot) ([]agent.Agent, error)
- func (c *Claude) FindSessionFile(a agent.Agent) string
- func (c *Claude) Kill(a agent.Agent) error
- func (c *Claude) Name() string
- func (c *Claude) OTELEnv(endpoint string) string
- func (c *Claude) OTELServiceName() string
- func (c *Claude) ParseTrace(filePath string) ([]trace.Turn, error)
- func (c *Claude) RecentDirs(max int) []RecentDir
- func (c *Claude) ResumeCommand(a agent.Agent) *exec.Cmd
- func (c *Claude) SpawnArgs() SpawnArgs
- func (c *Claude) SpawnCommand(dir, model, mode string) *exec.Cmd
- func (c *Claude) SubagentAttrKeys() subagent.AttrKeys
- type Codex
- func (c *Codex) CanEmbed() bool
- func (c *Codex) Discover() ([]agent.Agent, error)
- func (c *Codex) DiscoverWithSnapshot(snap *discovery.Snapshot) ([]agent.Agent, error)
- func (c *Codex) FindSessionFile(a agent.Agent) string
- func (c *Codex) Kill(a agent.Agent) error
- func (c *Codex) Name() string
- func (c *Codex) OTELEnv(endpoint string) string
- func (c *Codex) OTELServiceName() string
- func (c *Codex) ParseTrace(filePath string) ([]trace.Turn, error)
- func (c *Codex) RecentDirs(max int) []RecentDir
- func (c *Codex) ResumeCommand(a agent.Agent) *exec.Cmd
- func (c *Codex) SpawnArgs() SpawnArgs
- func (c *Codex) SpawnCommand(dir, model, mode string) *exec.Cmd
- func (c *Codex) SubagentAttrKeys() subagent.AttrKeys
- type Gemini
- func (g *Gemini) CanEmbed() bool
- func (g *Gemini) Discover() ([]agent.Agent, error)
- func (g *Gemini) DiscoverWithSnapshot(snap *discovery.Snapshot) ([]agent.Agent, error)
- func (g *Gemini) FindSessionFile(a agent.Agent) string
- func (g *Gemini) Kill(a agent.Agent) error
- func (g *Gemini) Name() string
- func (g *Gemini) OTELEnv(endpoint string) string
- func (g *Gemini) OTELServiceName() string
- func (g *Gemini) ParseTrace(filePath string) ([]trace.Turn, error)
- func (g *Gemini) RecentDirs(max int) []RecentDir
- func (g *Gemini) ResumeCommand(a agent.Agent) *exec.Cmd
- func (g *Gemini) SpawnArgs() SpawnArgs
- func (g *Gemini) SpawnCommand(dir, model, mode string) *exec.Cmd
- func (g *Gemini) SubagentAttrKeys() subagent.AttrKeys
- type HealthStatus
- type InfraProvider
- type K8s
- func (k *K8s) CanEmbed() bool
- func (k *K8s) CheckHealth() HealthStatus
- func (k *K8s) Close()
- func (k *K8s) Discover() ([]agent.Agent, error)
- func (k *K8s) FindSessionFile(a agent.Agent) string
- func (k *K8s) GetTaskResult(taskID string) (string, error)
- func (k *K8s) Kill(a agent.Agent) error
- func (k *K8s) ListTasks() ([]task.Task, error)
- func (k *K8s) Name() string
- func (k *K8s) OTELEnv(_ string) string
- func (k *K8s) OTELServiceName() string
- func (k *K8s) ParseTrace(filePath string) ([]trace.Turn, error)
- func (k *K8s) RecentDirs(_ int) []RecentDir
- func (k *K8s) ResumeCommand(_ agent.Agent) *exec.Cmd
- func (k *K8s) ScaleDown(provider, role string) error
- func (k *K8s) ScaleDownOne(providerName, role string) error
- func (k *K8s) SendMessage(agentID, text string) error
- func (k *K8s) SpawnArgs() SpawnArgs
- func (k *K8s) SpawnCommand(_, _, _ string) *exec.Cmd
- func (k *K8s) SpawnRemote(provider, role string, count int) error
- func (k *K8s) SpawnSession(providerName string) (podName, namespace string, err error)
- func (k *K8s) Status() string
- func (k *K8s) SubagentAttrKeys() subagent.AttrKeys
- type K8sConfig
- type Messenger
- type OpenShell
- func (o *OpenShell) CanEmbed() bool
- func (o *OpenShell) Discover() ([]agent.Agent, error)
- func (o *OpenShell) FindSessionFile(a agent.Agent) string
- func (o *OpenShell) Kill(a agent.Agent) error
- func (o *OpenShell) Name() string
- func (o *OpenShell) OTELEnv(endpoint string) string
- func (o *OpenShell) OTELServiceName() string
- func (o *OpenShell) ParseTrace(filePath string) ([]trace.Turn, error)
- func (o *OpenShell) RecentDirs(max int) []RecentDir
- func (o *OpenShell) ResumeCommand(a agent.Agent) *exec.Cmd
- func (o *OpenShell) SpawnArgs() SpawnArgs
- func (o *OpenShell) SpawnCommand(dir, model, mode string) *exec.Cmd
- func (o *OpenShell) SubagentAttrKeys() subagent.AttrKeys
- type Provider
- type ProviderHealth
- type RecentDir
- type Role
- type Segment
- type SpawnArgs
- type Spawner
- type SystemHealth
- type TaskLister
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatHealth ¶ added in v0.7.0
func FormatHealth(sh SystemHealth) string
FormatHealth renders SystemHealth as a human-readable string. This is used by the TUI health view but lives here so it can be tested without TUI dependencies.
func KillLocalAgent ¶ added in v0.7.0
KillLocalAgent sends SIGTERM to the agent's process tree, waits 3 seconds, then SIGKILL if still alive. Also kills the associated tmux session if one exists. Used by all local providers (Claude, Codex, Gemini). Remote providers (e.g., Kubernetes) should implement their own Kill method.
Types ¶
type Claude ¶
type Claude struct{}
Claude is a Provider implementation for the Claude Code CLI.
func (*Claude) Discover ¶
Discover finds all running Claude Code processes, then enriches each agent with CWD, tmux session, session JSONL data, and estimated cost. SDK-spawned agents sharing the same directory and model are grouped into single entries.
func (*Claude) DiscoverWithSnapshot ¶ added in v0.8.1
DiscoverWithSnapshot uses a shared ps/tmux snapshot instead of running its own subprocess calls.
func (*Claude) FindSessionFile ¶
FindSessionFile resolves the session/trace file for a Claude agent. It first tries the session ID lookup, then falls back to finding the newest JSONL in the agent's working directory.
func (*Claude) OTELEnv ¶
OTELEnv returns env vars to enable Claude Code's OTEL tracing. Sets both generic and signal-specific endpoints with explicit paths to avoid OTEL SDK path-appending issues across different Node.js SDK versions. Uses http/protobuf protocol (port 4318).
func (*Claude) OTELServiceName ¶ added in v0.5.0
func (*Claude) ParseTrace ¶
ParseTrace reads a Claude JSONL session file and parses it into trace turns.
func (*Claude) RecentDirs ¶
RecentDirs returns recently-used project directories from Claude's session history (~/.claude/projects/). Each subdirectory is a dir-key (the encoded working directory path). The newest .jsonl in each subdirectory determines LastUsed.
func (*Claude) SpawnCommand ¶
SpawnCommand builds the exec.Cmd to launch a new Claude session.
Flags:
- --model <model> if model is set and not "default"
- --dangerously-skip-permissions if mode == "bypass"
- --permission-mode plan if mode == "plan"
func (*Claude) SubagentAttrKeys ¶ added in v0.5.0
SubagentAttrKeys returns the OTEL attribute names Claude uses for subagent identity.
type Codex ¶
type Codex struct{}
Codex is a Provider implementation for the OpenAI Codex CLI.
func (*Codex) CanEmbed ¶
CanEmbed returns false — Codex's TUI hangs inside an embedded PTY even with --no-alt-screen. Use trace view + J to jump out instead.
func (*Codex) Discover ¶
Discover finds running Codex CLI processes and recent session files. Running processes are discovered via ps; recent sessions (last 24h) without a running process are shown as idle so they can be resumed.
func (*Codex) DiscoverWithSnapshot ¶ added in v0.8.1
DiscoverWithSnapshot uses a shared ps/tmux snapshot.
func (*Codex) FindSessionFile ¶
FindSessionFile resolves the session/trace file for a Codex agent. Returns "" if the agent has no WorkingDir or if the session file is stale (not modified in the last 24 hours).
func (*Codex) OTELEnv ¶
OTELEnv returns env vars to enable Codex CLI's OTEL tracing. Codex exports both traces (session spans) and log events.
func (*Codex) OTELServiceName ¶ added in v0.5.0
func (*Codex) ParseTrace ¶
ParseTrace reads a Codex JSONL session file and parses it into trace turns.
func (*Codex) RecentDirs ¶
RecentDirs returns recently-used project directories from Codex's session history (~/.codex/sessions/). Scans recursively for .jsonl files from the last 30 days, reads session_meta for CWD, deduplicates by path, sorts by newest first, and caps at max.
func (*Codex) SpawnCommand ¶
SpawnCommand builds the exec.Cmd to launch a new Codex session.
Flags:
- --no-alt-screen always
- --model <model> if model is set and not "default"
- --full-auto if mode == "full-auto"
- --sandbox workspace-write if mode is empty or "default"
func (*Codex) SubagentAttrKeys ¶ added in v0.5.0
SubagentAttrKeys returns zero AttrKeys — Codex doesn't support subagent tracking.
type Gemini ¶
type Gemini struct{}
Gemini is a Provider implementation for the Google Gemini CLI.
func (*Gemini) CanEmbed ¶
CanEmbed returns false because Gemini's TUI cannot run inside an embedded PTY.
func (*Gemini) Discover ¶
Discover finds running Gemini CLI processes and enriches them with session data from ~/.gemini/tmp/<project>/chats/.
func (*Gemini) DiscoverWithSnapshot ¶ added in v0.8.1
DiscoverWithSnapshot uses a shared ps/tmux snapshot.
func (*Gemini) FindSessionFile ¶
FindSessionFile resolves the session file for a Gemini agent. If the agent has a SessionID, it finds the matching session-*.json in chats/. Otherwise it falls back to the newest session file.
func (*Gemini) OTELEnv ¶
OTELEnv returns env vars to enable Gemini CLI's OTEL tracing. Gemini exports traces, metrics, and logs.
func (*Gemini) OTELServiceName ¶ added in v0.5.0
func (*Gemini) ParseTrace ¶
ParseTrace reads a Gemini session file and parses it into trace turns. Supports both logs.json (array of log entries) and session-*.json (session object with messages array) formats.
func (*Gemini) RecentDirs ¶
RecentDirs returns recently-used project directories from Gemini's projects.json, sorted by most recent session activity.
func (*Gemini) ResumeCommand ¶
ResumeCommand builds the command to resume the latest Gemini session.
func (*Gemini) SpawnCommand ¶
SpawnCommand builds the exec.Cmd to launch a new Gemini session.
Flags:
- --model <model> if model is set and not "default"
- --yolo if mode == "yolo"
- --approval-mode plan if mode == "plan"
func (*Gemini) SubagentAttrKeys ¶ added in v0.5.0
SubagentAttrKeys returns zero AttrKeys — Gemini doesn't support subagent tracking.
type HealthStatus ¶ added in v0.7.0
type HealthStatus struct {
Configured bool // true if the backend is configured
CoordOK bool // coordination layer healthy (Redis, SQS, etc.)
CoordErr string // coordination error message
ComputeOK bool // compute layer healthy (K8s API, EC2 API, etc.)
ComputeErr string // compute error message
Workloads []string // discovered workload names (deployments, instances, etc.)
}
HealthStatus represents the readiness of a infra provider's infrastructure. The two-layer model (coordination + compute) maps to any backend:
K8s: CoordOK=Redis, ComputeOK=cluster API EC2: CoordOK=SQS/DynamoDB, ComputeOK=EC2 API SSH: CoordOK=control host, ComputeOK=target host reachable
type InfraProvider ¶ added in v0.7.0
type InfraProvider interface {
Provider
TaskLister
Spawner
// Status returns a human-readable connection status for display.
Status() string
// CheckHealth validates connectivity to backing infrastructure.
// The returned HealthStatus uses generic fields that map to any
// backend's coordination + compute layers.
CheckHealth() HealthStatus
// SpawnSession creates a new interactive session instance and waits
// for it to become ready. Returns the instance name and namespace
// (or region, availability zone, etc. depending on the backend).
SpawnSession(providerName string) (instanceName, namespace string, err error)
// ScaleDownOne removes one instance of the named workload.
ScaleDownOne(providerName, role string) error
}
InfraProvider is an optional interface for providers that manage remote agent infrastructure (Kubernetes, EC2, SSH hosts, etc.). The TUI stores one of these for on-demand operations (spawn sessions, health checks, status display). Each backend implements its own discovery, spawning, and health check logic behind this interface.
if rp, ok := p.(provider.InfraProvider); ok { rp.Status() }
type K8s ¶ added in v0.7.0
type K8s struct {
// contains filtered or unexported fields
}
K8s is a Provider implementation for Kubernetes-hosted AI agents. Agents are discovered via Redis heartbeats rather than local process scanning. This provider never embeds a PTY — agents run in pods and are viewed trace-only.
func (*K8s) CanEmbed ¶ added in v0.7.0
CanEmbed returns false — K8s agents run in pods and cannot be embedded as a local PTY. The TUI shows trace-only view with a jump-out option.
func (*K8s) CheckHealth ¶ added in v0.7.0
func (k *K8s) CheckHealth() HealthStatus
CheckHealth probes Redis and K8s connectivity. Designed to be called once when the :new picker opens — not on every tick. Each check has a 1-second timeout.
func (*K8s) Close ¶ added in v0.7.0
func (k *K8s) Close()
Close shuts down the shared Redis client if one was created. Safe to call multiple times or when no client was initialized.
func (*K8s) Discover ¶ added in v0.7.0
Discover reads Redis heartbeats and agent metadata to enumerate live and recently-seen K8s agents. Returns (nil, nil) when RedisURL is not configured so that a missing Redis setup never crashes aimux on startup.
Status assignment:
- Active: heartbeat < 30 s ago
- Idle: heartbeat 30–60 s ago
- Unknown: heartbeat > 60 s ago (dead but still shown)
func (*K8s) FindSessionFile ¶ added in v0.7.0
FindSessionFile returns a "k8s://<sessionID>" sentinel so the trace pane can pass it to ParseTrace, which uses it to query Redis task history.
func (*K8s) GetTaskResult ¶ added in v0.7.0
GetTaskResult returns the full result reference for a task by delegating to task.GetFullResult. Returns ("", nil) when Redis is not configured. Implements the optional TaskLister interface.
func (*K8s) Kill ¶ added in v0.7.0
Kill delegates to K8sBackend to scale down the agent's deployment by 1.
func (*K8s) ListTasks ¶ added in v0.7.0
ListTasks returns all tasks for the configured team by delegating to task.LoadFromRedis. Returns (nil, nil) when Redis is not configured. Implements the optional TaskLister interface.
func (*K8s) OTELEnv ¶ added in v0.7.0
OTELEnv returns "" — K8s agents configure their own OTEL settings via pod environment variables managed outside aimux.
func (*K8s) OTELServiceName ¶ added in v0.7.0
OTELServiceName returns the service.name for K8s agents in OTEL telemetry.
func (*K8s) ParseTrace ¶ added in v0.7.0
ParseTrace reads completed task history from Redis for the agent identified by filePath. For this provider filePath is unused (FindSessionFile returns ""); the caller passes the agent's SessionID via the agent struct. Because the current Provider interface passes only filePath, we return an informational turn explaining how to view task history.
Design note: full task history requires the agent's SessionID. The interface contract passes filePath (empty for K8s). Returning a descriptive single Turn gives the user useful information without panicking or returning an error that would suppress the trace view entirely. ParseTrace reads completed task history from Redis using the agentID encoded in filePath as "k8s://<agentID>". Each completed task becomes one trace Turn. Returns an informational Turn if Redis is unconfigured or filePath is not a k8s:// sentinel.
func (*K8s) RecentDirs ¶ added in v0.7.0
RecentDirs returns nil — K8s agents do not work on local directories.
func (*K8s) ResumeCommand ¶ added in v0.7.0
ResumeCommand returns nil. K8s agents cannot be resumed as local processes.
func (*K8s) ScaleDown ¶ added in v0.7.0
ScaleDown delegates to K8sBackend to scale the deployment to 0.
func (*K8s) ScaleDownOne ¶ added in v0.7.0
ScaleDownOne delegates to K8sBackend to decrement the deployment by 1.
func (*K8s) SendMessage ¶ added in v0.7.0
SendMessage writes a message to the agent's Redis inbox stream. Implements the optional Messenger interface.
func (*K8s) SpawnArgs ¶ added in v0.7.0
SpawnArgs describes the models and modes available when launching a K8s agent.
func (*K8s) SpawnCommand ¶ added in v0.7.0
SpawnCommand returns nil — K8s agents are not spawned locally.
func (*K8s) SpawnRemote ¶ added in v0.7.0
SpawnRemote scales up the Kubernetes Deployment named "agent-{provider}-{role}" by the specified count. Returns an error if the kube client cannot be constructed or the deployment cannot be created/scaled. Implements the optional Spawner interface.
func (*K8s) SpawnSession ¶ added in v0.7.0
SpawnSession delegates to the K8sBackend to create a session pod and wait for it to become ready. Returns the pod name and namespace.
func (*K8s) Status ¶ added in v0.7.0
Status returns a human-readable connection status for display in the TUI.
func (*K8s) SubagentAttrKeys ¶ added in v0.7.0
SubagentAttrKeys returns zero value — K8s agents do not emit subagent identity attributes in the format aimux's OTEL receiver understands.
type K8sConfig ¶ added in v0.7.0
type K8sConfig struct {
RedisURL string // e.g. "redis://:pass@localhost:6380"
TeamID string // e.g. "my-team"
Namespace string // K8s namespace, e.g. "agents"
Kubeconfig string // path to kubeconfig; empty = in-cluster or KUBECONFIG env
}
K8sConfig holds connection settings for the Kubernetes provider. All fields may be populated from ~/.aimux/config.yaml under the "kubernetes" key.
type Messenger ¶ added in v0.7.0
Messenger is an optional interface for providers that support sending messages to a specific agent (e.g. writing to a Redis inbox stream). Check with: if m, ok := p.(provider.Messenger); ok { m.SendMessage(...) }
type OpenShell ¶ added in v0.9.0
type OpenShell struct{}
OpenShell discovers agents running in NVIDIA OpenShell sandboxes. Architecture placeholder. Functional implementation follows once OpenShell's API stabilizes. Integration plan: discover sandboxes via openshell sandbox list, connect via openshell sandbox connect.
func (*OpenShell) FindSessionFile ¶ added in v0.9.0
func (*OpenShell) OTELServiceName ¶ added in v0.9.0
func (*OpenShell) ParseTrace ¶ added in v0.9.0
func (*OpenShell) RecentDirs ¶ added in v0.9.0
func (*OpenShell) ResumeCommand ¶ added in v0.9.0
func (*OpenShell) SpawnCommand ¶ added in v0.9.0
func (*OpenShell) SubagentAttrKeys ¶ added in v0.9.0
type Provider ¶
type Provider interface {
Name() string
Discover() ([]agent.Agent, error)
ResumeCommand(a agent.Agent) *exec.Cmd
// CanEmbed returns true if the agent's TUI can run inside an
// embedded PTY (split view). False means trace-only view with
// jump-out for interaction.
CanEmbed() bool
// FindSessionFile resolves the session/trace file for an agent.
// Each provider knows its own storage layout. Returns "" if none found.
FindSessionFile(a agent.Agent) string
// RecentDirs returns recently-used project directories from this
// provider's session history, sorted by most recent first.
RecentDirs(max int) []RecentDir
// SpawnCommand builds the exec.Cmd to launch a new agent session
// in the given directory with the specified model and mode.
SpawnCommand(dir, model, mode string) *exec.Cmd
// SpawnArgs returns the available models and modes for the launcher UI.
SpawnArgs() SpawnArgs
// ParseTrace reads a session/trace file and parses it into a
// provider-specific structured trace. Each provider knows its own
// log format (Claude JSONL, Codex JSONL, Gemini JSON).
ParseTrace(filePath string) ([]trace.Turn, error)
// OTELEnv returns the shell env var prefix needed to enable OTEL
// tracing for this provider, pointing at the given endpoint.
// Each provider knows its own OTEL activation mechanism.
OTELEnv(endpoint string) string
// OTELServiceName returns the service.name value this provider
// emits in OTEL resource attributes (e.g. "claude-code").
OTELServiceName() string
// SubagentAttrKeys returns the OTEL attribute names this provider
// uses for subagent identity. Return zero AttrKeys if the provider
// doesn't support subagent tracking.
SubagentAttrKeys() subagent.AttrKeys
// Kill stops the agent. For local providers, this sends SIGTERM/SIGKILL
// to the process tree. For infra providers (e.g., Kubernetes), this
// deletes the pod or scales down the deployment.
Kill(a agent.Agent) error
}
Provider discovers and manages AI CLI agents of a specific type. Adding a new provider requires only implementing this interface and registering in app.go NewApp() — no other files need changes.
type ProviderHealth ¶ added in v0.7.0
type ProviderHealth struct {
Name string // e.g. "claude", "k8s"
Kind string // "local" or "infra"
BinaryPath string // resolved path to the binary (local only)
BinaryOK bool // true if binary is found in PATH
Version string // binary version string (local only)
Agents int // number of currently active agents
Infra *HealthStatus // infra health details (infra only, nil for local)
}
ProviderHealth describes the health of a single provider.
type Segment ¶
type Segment struct {
Time time.Time
Role Role
Content string
Tool string // tool name if Role==RoleTool
Detail string // e.g., file path, command snippet
}
Segment is a single conversation turn, provider-agnostic.
type SpawnArgs ¶
type SpawnArgs struct {
Models []string // e.g., ["default", "opus", "sonnet", "haiku"]
Modes []string // e.g., ["default", "bypass", "plan"]
}
SpawnArgs describes the available options for launching a new agent.
type Spawner ¶ added in v0.7.0
type Spawner interface {
SpawnRemote(provider, role string, count int) error
ScaleDown(provider, role string) error
}
Spawner is an optional interface for providers that can spawn agents remotely. The TUI checks for this via type assertion:
if sp, ok := p.(provider.Spawner); ok { sp.SpawnRemote(...) }
type SystemHealth ¶ added in v0.7.0
type SystemHealth struct {
Providers []ProviderHealth
}
SystemHealth holds the health of all providers and infra.
func GatherHealth ¶ added in v0.7.0
func GatherHealth(providers []Provider, infra InfraProvider, agentCounts map[string]int) SystemHealth
GatherHealth collects health from all providers and an optional infra provider. Each local provider's binary is checked via exec.LookPath. Agent counts come from the most recent discovery results.
type TaskLister ¶ added in v0.7.0
type TaskLister interface {
ListTasks() ([]task.Task, error)
GetTaskResult(taskID string) (string, error)
}
TaskLister is an optional interface for providers that support task management. The TUI checks for this via type assertion:
if tl, ok := p.(provider.TaskLister); ok { tasks, _ := tl.ListTasks() }