API Reference

// Task represents a unit of work for the agent
type Task interface {
    GetID() string
    GetTitle() string
    GetDescription() string
    GetBranchName() string
    GetLabels() []string
    GetMetadata() TaskMetadata
}

type TaskMetadata struct {
    Source    TaskSource  // "linear", "prompt", "file"
    CreatedAt time.Time
    FilePath  string     // Only for file-based tasks
}

type TaskSource string
 
const (
    TaskSourceLinear TaskSource = "linear"
    TaskSourcePrompt TaskSource = "prompt"
    TaskSourceFile   TaskSource = "file"
)

type Config struct {
    LinearKey      string        // Linear API key
    BaseBranch     string        // Base branch (default: "main")
    MaxIterations  int           // Max review/refactor cycles (default: 5)
    ReviewSkill    string        // Claude skill for review (default: "peer-review")
    EnableTools    bool          // Enable Claude tools (default: true)
    AutoPR         bool          // Auto-create PR (default: true)
 
    // Feature toggles
    EnablePreflight  bool
    EnableTests      bool
    EnableDiffVerify bool
    EnableMemory     bool
    CheckpointDir    string
    MemoryDir        string
 
    // Sub-configs
    Claude      ClaudeConfig
    Review      ReviewConfig
    Coordinator CoordinatorConfig
    Retry       RetryConfig
    TokenBudget TokenBudgetConfig
}

type ClaudeConfig struct {
    Command              string  // CLI command (default: "claude")
    UseTmux              bool    // Use tmux for large prompts
    LargePromptThreshold int     // Character count for tmux
    Timeout              int     // Timeout in seconds (0 = no timeout)
    EnablePromptCaching  bool    // Enable prompt caching
 
    Models struct {
        Planner    string  // Model for planning
        Executor   string  // Model for execution
        Reviewer   string  // Model for review
        Refactor   string  // Model for refactoring
        Preflight  string  // Model for preflight validation
        TestRunner string  // Model for test parsing
    }
}

type ReviewConfig struct {
    MaxCriticalIssues         int   // Max critical issues to pass (default: 1)
    MaxMajorIssues            int   // Max major issues to pass (default: 3)
    MinVerificationConfidence int   // Min confidence % (default: 50)
    StrictParsing             bool  // Strict keyword parsing (default: false)
}

type CoordinatorConfig struct {
    MessageBufferSize    int  // Main channel buffer (default: 1000)
    SubscriberBufferSize int  // Per-agent buffer (default: 100)
}

type RetryConfig struct {
    MaxAttempts  int           // Number of attempts (default: 3)
    InitialDelay time.Duration // Initial delay (default: 500ms)
    MaxDelay     time.Duration // Max delay (default: 30s)
}

type Agent struct {
    Config *config.Config
}
 
func New(cfg *config.Config) (*Agent, error)
func (a *Agent) Work(ctx context.Context, t task.Task) (*WorkResult, error)

type WorkResult struct {
    PRCreated bool   // Whether a PR was created
    PRURL     string // URL of the created PR
    Message   string // Status message
}

type Event struct {
    Type        string                 `json:"type"`
    ID          string                 `json:"id,omitempty"`
    Name        string                 `json:"name,omitempty"`
    Description string                 `json:"description,omitempty"`
    Status      string                 `json:"status,omitempty"`
    Message     string                 `json:"message,omitempty"`
    Data        map[string]interface{} `json:"data,omitempty"`
}

func Emit(event Event)
func AgentStarted(id, name, description string)
func AgentCompleted(id, name, status string)
func AgentCompletedWithData(id, name, status string, data map[string]interface{})
func TaskCreated(id, name, description string)
func TaskUpdated(id, status string)
func Progress(message string)

type Coordinator struct{}
 
func NewCoordinator(cfg *config.CoordinatorConfig) *Coordinator
func (c *Coordinator) Start()
func (c *Coordinator) Stop()
func (c *Coordinator) ClaimWork(agentID string, claim *WorkClaim) error
func (c *Coordinator) LockFiles(agentID string, files []string) error
func (c *Coordinator) UnlockFiles(agentID string) error
func (c *Coordinator) SetContext(key string, value interface{})
func (c *Coordinator) GetContext(key string) (interface{}, bool)

type WorkClaim struct {
    WorkID string
    Files  []string
}

type Checkpoint struct {
    TaskID    string
    Step      string
    Iteration int
    State     []byte // Serialized agent state
}
 
func Save(cp *Checkpoint) error
func Load(taskID string) (*Checkpoint, error)
func Rollback(taskID string, step string) error
func Squash(message string) error
func Snapshot(name string) error

func Do(ctx context.Context, fn func() error, opts ...Option) error
func WithMaxAttempts(n int) Option
func WithInitialDelay(d time.Duration) Option
func WithMaxDelay(d time.Duration) Option
func IsPermanent(err error) bool
func NewPermanentError(err error) error

func CheckAll() (*HealthReport, error)
func CheckGit() error
func CheckGH() error
func CheckClaude() error
func CheckTmux() error

type HealthReport struct {
    Passed  []string
    Failed  []string
    Warnings []string
}