Documentation
¶
Overview ¶
Package agent provides types and utilities for parsing and managing AI agent state. This includes detecting agent status from terminal output, determining context usage, and recommending actions based on current state.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentState ¶
type AgentState struct {
// Identity
Type AgentType `json:"agent_type"`
ParsedAt time.Time `json:"parsed_at"`
// Quantitative metrics (nil = unknown/not available)
// Using pointers allows distinguishing "unknown" from "zero"
ContextRemaining *float64 `json:"context_remaining,omitempty"` // 0-100 percentage remaining
TokensUsed *int64 `json:"tokens_used,omitempty"` // Total tokens consumed
MemoryMB *float64 `json:"memory_mb,omitempty"` // Memory usage (Gemini)
// Qualitative state flags
IsWorking bool `json:"is_working"` // Actively producing output (DO NOT INTERRUPT)
IsRateLimited bool `json:"rate_limited"` // Hit API usage limit (wait for reset)
IsContextLow bool `json:"context_low"` // Below configured threshold
IsIdle bool `json:"is_idle"` // Waiting for user input (safe to restart)
IsInError bool `json:"is_in_error"` // Error state detected
// Evidence for debugging and confidence calculation
WorkIndicators []string `json:"work_indicators,omitempty"` // Patterns that indicate working
LimitIndicators []string `json:"limit_indicators,omitempty"` // Patterns that indicate rate limiting
RawSample string `json:"raw_sample,omitempty"` // Last N chars for debugging
// Confidence in this assessment (0.0-1.0)
// Higher confidence means more pattern matches or explicit indicators
Confidence float64 `json:"confidence"`
}
AgentState represents the parsed state from agent terminal output. This is used to determine whether an agent is working, rate-limited, running low on context, or idle and ready for new work.
func (*AgentState) GetRecommendation ¶
func (s *AgentState) GetRecommendation() Recommendation
GetRecommendation derives the recommended action from the current state. Priority order is carefully chosen:
- Rate limited -> wait (highest priority, nothing we can do)
- Error state -> handle error
- Working -> DO NOT INTERRUPT (critical user requirement)
- Idle -> safe to restart
- Unknown -> be cautious
type AgentType ¶
type AgentType string
AgentType identifies which CLI agent is running in a pane.
const ( AgentTypeClaudeCode AgentType = "cc" // Claude Code CLI AgentTypeCodex AgentType = "cod" // Codex CLI (OpenAI) AgentTypeGemini AgentType = "gmi" // Gemini CLI (Google) AgentTypeOllama AgentType = "ollama" // Local Ollama CLI AgentTypeCursor AgentType = "cursor" // Cursor AI AgentTypeWindsurf AgentType = "windsurf" // Windsurf IDE AgentTypeAider AgentType = "aider" // Aider CLI AgentTypeUser AgentType = "user" // User/Shell pane AgentTypeUnknown AgentType = "unknown" // Unable to determine agent type )
func (AgentType) DisplayName ¶
DisplayName returns a human-readable name for the agent type.
func (AgentType) ProfileName ¶
ProfileName returns the friendly display name for the agent type (short form).
type Parser ¶
type Parser interface {
// Parse analyzes terminal output and returns structured agent state.
// The output parameter is raw text captured from a tmux pane.
Parse(output string) (*AgentState, error)
// ParseWithHint analyzes terminal output with a known agent type hint.
// This skips type detection if the hint is valid, improving performance and accuracy.
ParseWithHint(output string, hint AgentType) (*AgentState, error)
// DetectAgentType identifies which agent type produced the output.
// This is useful when the agent type is not known in advance.
DetectAgentType(output string) AgentType
}
Parser defines the interface for extracting AgentState from terminal output. Implementations parse raw text captured from tmux panes and extract structured state information.
func NewParserWithConfig ¶
func NewParserWithConfig(cfg ParserConfig) Parser
NewParserWithConfig creates a parser with custom configuration.
type ParserConfig ¶
type ParserConfig struct {
// ContextLowThreshold is the percentage below which context is considered low.
// Default: 20.0 (flag when below 20% remaining)
ContextLowThreshold float64
// SampleLength is the number of characters to keep in RawSample for debugging.
// Default: 500
SampleLength int
}
ParserConfig holds configuration for parser behavior.
func DefaultParserConfig ¶
func DefaultParserConfig() ParserConfig
DefaultParserConfig returns the default parser configuration.
type PatternSet ¶
type PatternSet struct {
RateLimitPatterns []string
WorkingPatterns []string
IdlePatterns []*regexp.Regexp
ErrorPatterns []string
ContextWarnings []string // Only used by Claude Code
ContextPattern *regexp.Regexp // Explicit context extraction (Codex)
TokenPattern *regexp.Regexp // Token usage extraction
MemoryPattern *regexp.Regexp // Memory usage (Gemini)
HeaderPattern *regexp.Regexp
}
PatternSet groups all patterns for a specific agent type. This makes it easier to pass around and test pattern collections.
func GetPatternSet ¶
func GetPatternSet(agentType AgentType) *PatternSet
GetPatternSet returns the pattern set for the given agent type.
type Recommendation ¶
type Recommendation string
Recommendation represents the recommended action based on agent state.
const ( // RecommendDoNotInterrupt means the agent is actively working and should not be interrupted. // This is the highest priority state - never interrupt agents doing useful work. RecommendDoNotInterrupt Recommendation = "DO_NOT_INTERRUPT" // RecommendSafeToRestart means the agent is idle and can safely be restarted or given new work. RecommendSafeToRestart Recommendation = "SAFE_TO_RESTART" // RecommendContextLowContinue means the agent is working but running low on context. // Let it finish current work, then proactively restart before hitting limits. RecommendContextLowContinue Recommendation = "CONTEXT_LOW_CONTINUE" // RecommendRateLimitedWait means the agent hit an API usage limit. // Wait for the rate limit to reset before taking action. RecommendRateLimitedWait Recommendation = "RATE_LIMITED_WAIT" // RecommendErrorState means the agent is in an error state and may need intervention. RecommendErrorState Recommendation = "ERROR_STATE" // RecommendUnknown means we couldn't determine the agent state with confidence. RecommendUnknown Recommendation = "UNKNOWN" )
func (Recommendation) IsActionable ¶
func (r Recommendation) IsActionable() bool
IsActionable returns true if this recommendation suggests taking action (as opposed to waiting or being uncertain).
func (Recommendation) RequiresWaiting ¶
func (r Recommendation) RequiresWaiting() bool
RequiresWaiting returns true if this recommendation suggests waiting before taking action.
func (Recommendation) String ¶
func (r Recommendation) String() string
String returns a human-readable representation of the recommendation.
Source Files
Directories