agent

Documentation

Overview

Package agent launches the `claude` CLI inside a worktree, either interactively (inheriting the terminal) or headlessly (`claude -p`, capturing output). The Launcher interface is consumed by the cli/crew/session layers; Claude is the implementation.

Index

• func ProbeVersion(ctx context.Context, binary string) (string, error)
• type Claude
  • func NewClaude(cfg config.ClaudeConfig, log *zerolog.Logger) (*Claude, error)
  • func (c *Claude) Binary() string
  • func (c *Claude) Headless(ctx context.Context, wt domain.Worktree, spec HeadlessSpec) (HeadlessResult, error)
  • func (c *Claude) HeadlessArgs(spec HeadlessSpec) []string
  • func (c *Claude) Interactive(ctx context.Context, wt domain.Worktree, spec InteractiveSpec) (int, error)
  • func (c *Claude) InteractiveArgs(spec InteractiveSpec) []string
• type HeadlessResult
• type HeadlessSpec
• type InteractiveSpec
• type Launcher
• type Spec
• type StreamEvent

Functions

func ProbeVersion

func ProbeVersion(ctx context.Context, binary string) (string, error)

ProbeVersion returns the output of `claude --version`.

Types

type Claude

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

Claude is the Launcher backed by the claude CLI.

func NewClaude

func NewClaude(cfg config.ClaudeConfig, log *zerolog.Logger) (*Claude, error)

NewClaude resolves the claude binary and returns a Launcher.

func (*Claude) Binary

func (c *Claude) Binary() string

func (*Claude) Headless

func (c *Claude) Headless(ctx context.Context, wt domain.Worktree, spec HeadlessSpec) (HeadlessResult, error)

Headless runs `claude -p` with cwd = wt.Path and captures the result.

func (*Claude) HeadlessArgs

func (c *Claude) HeadlessArgs(spec HeadlessSpec) []string

HeadlessArgs returns the argv for a `claude -p` run.

func (*Claude) Interactive

func (c *Claude) Interactive(ctx context.Context, wt domain.Worktree, spec InteractiveSpec) (int, error)

Interactive runs claude attached to the current terminal (stdio inherited), with cwd = wt.Path. Blocks until claude exits; returns its exit code.

func (*Claude) InteractiveArgs

func (c *Claude) InteractiveArgs(spec InteractiveSpec) []string

InteractiveArgs returns the argv for an interactive run (prompt is the final positional argument, if any).

type HeadlessResult

type HeadlessResult struct {
	SessionID  string          `json:"session_id,omitempty"`
	Text       string          `json:"text"`
	IsError    bool            `json:"is_error"`
	DurationMS int64           `json:"duration_ms,omitempty"`
	CostUSD    float64         `json:"cost_usd,omitempty"`
	NumTurns   int             `json:"num_turns,omitempty"`
	ExitCode   int             `json:"exit_code"`
	Stderr     string          `json:"stderr,omitempty"`
	Raw        json.RawMessage `json:"-"`
}

HeadlessResult is the parsed outcome of a `claude -p` run. Raw retains the full envelope so we stay resilient to claude output-shape changes.

type HeadlessSpec

type HeadlessSpec struct {
	Spec
	OutputFormat  string            // text|json|stream-json
	FallbackModel string            // --fallback-model
	MaxBudgetUSD  float64           // --max-budget-usd
	Timeout       time.Duration     // 0 => ClaudeConfig.Headless.TimeoutSeconds
	StreamHandler func(StreamEvent) // optional; only for stream-json
}

HeadlessSpec configures a headless (`-p`) run.

type InteractiveSpec

type InteractiveSpec struct{ Spec }

InteractiveSpec configures an interactive run.

type Launcher

type Launcher interface {
	Interactive(ctx context.Context, wt domain.Worktree, spec InteractiveSpec) (exitCode int, err error)
	Headless(ctx context.Context, wt domain.Worktree, spec HeadlessSpec) (HeadlessResult, error)
	// InteractiveArgs / HeadlessArgs return the exact argv Shepherd would run
	// (used by the session backend to host the process).
	InteractiveArgs(spec InteractiveSpec) []string
	HeadlessArgs(spec HeadlessSpec) []string
	// Binary returns the resolved claude executable path.
	Binary() string
}

Launcher runs claude.

type Spec

type Spec struct {
	Prompt             string   // positional prompt / task instructions
	Model              string   // --model
	PermissionMode     string   // --permission-mode
	SkipPermissions    bool     // --dangerously-skip-permissions
	Effort             string   // --effort
	AddDirs            []string // --add-dir (worktree dir is the cwd, so usually unnecessary)
	AppendSystemPrompt string   // --append-system-prompt
	AllowedTools       []string // --allowed-tools (joined space-separated)
	DisallowedTools    []string // --disallowed-tools
	ContinueSession    bool     // -c/--continue
	ResumeSessionID    string   // -r/--resume <id>
	SessionID          string   // --session-id <uuid>
	ForkSession        bool     // --fork-session
	ExtraArgs          []string // raw passthrough
}

Spec holds the config-derived knobs common to both modes. Zero values fall back to the ClaudeConfig defaults.

type StreamEvent

type StreamEvent struct {
	Type string          `json:"type"`
	Raw  json.RawMessage `json:"-"`
}

StreamEvent is one line of `--output-format stream-json` output.