Documentation
¶
Overview ¶
Package autopilot — self-direction backlog primitive that lets a Claude Code agent (the operator's clawtool driver) pull "what to work on next" without requiring the human to re-prompt every turn. The user calls this "devam edebilme yeteneği" — continuation ability / non-stalling.
Pattern: classic single-producer-multi-consumer task queue persisted as TOML. The operator (or the agent itself) appends items via AutopilotAdd; the agent dequeues via AutopilotNext, does the work, marks done via AutopilotDone, then loops. When Claim() returns ok=false the queue is empty and the agent ends the loop.
Why this is NOT BIAM/SendMessage: BIAM is agent-to-agent dispatch (codex / gemini / opencode). Autopilot is self-work — the SAME agent picking up its own backlog. Pre-this primitive an agent that finished a task either (a) stalled waiting for operator input, or (b) re-invented a TODO list in its scratchpad on every session.
Storage: a TOML file at $XDG_CONFIG_HOME/clawtool/autopilot/queue.toml (defaults to ~/.config/clawtool/autopilot/queue.toml). Per-host, not per-repo, so a backlog the operator wrote at lunch is still there when they reopen Claude Code in the evening. Atomic writes via internal/atomicfile so a crashed mid-rewrite never corrupts the queue.
Concurrency: Claim() takes an exclusive lock on the file (load → mutate → save under one rwmu acquisition). Two parallel "next" calls from a fanned-out agent will not return the same item — the tests pin this invariant.
Index ¶
- Variables
- func DefaultPath() string
- type Counts
- type Item
- type Queue
- func (q *Queue) Add(prompt string, priority int, note string) (Item, error)
- func (q *Queue) Claim() (Item, bool, error)
- func (q *Queue) Complete(id, note string) (Item, error)
- func (q *Queue) List(filter Status) ([]Item, error)
- func (q *Queue) Path() string
- func (q *Queue) Skip(id, note string) (Item, error)
- func (q *Queue) Status() (Counts, error)
- type Status
Constants ¶
This section is empty.
Variables ¶
var ErrAlreadyTerminal = errors.New("autopilot: item already in terminal state")
ErrAlreadyTerminal is returned by Complete / Skip when the item is already done or skipped. Callers can ignore for idempotency.
var ErrNotFound = errors.New("autopilot: item not found")
ErrNotFound is returned by Complete / Skip when no item matches the given id.
Functions ¶
func DefaultPath ¶
func DefaultPath() string
DefaultPath returns the canonical autopilot queue file: $XDG_CONFIG_HOME/clawtool/autopilot/queue.toml.
Types ¶
type Counts ¶
type Counts struct {
Pending int `json:"pending"`
InProgress int `json:"in_progress"`
Done int `json:"done"`
Skipped int `json:"skipped"`
Total int `json:"total"`
}
Counts represents the queue's status histogram. Returned by Status.
type Item ¶
type Item struct {
ID string `toml:"id" json:"id"`
Prompt string `toml:"prompt" json:"prompt"`
Priority int `toml:"priority" json:"priority"`
Status Status `toml:"status" json:"status"`
CreatedAt time.Time `toml:"created_at" json:"created_at"`
ClaimedAt time.Time `toml:"claimed_at,omitempty" json:"claimed_at,omitempty"`
DoneAt time.Time `toml:"done_at,omitempty" json:"done_at,omitempty"`
Note string `toml:"note,omitempty" json:"note,omitempty"`
}
Item is one unit of self-work. Field names map directly to TOML keys; preserve them when adding fields so existing queues survive rolling upgrades.
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue is a TOML-backed self-direction backlog. Construct with Open or OpenAt. Operations are concurrency-safe via an internal mutex; multiple Queue instances pointing at the same path serialize through the file system (atomicfile rename + every mutation does a fresh load).
func OpenAt ¶
OpenAt returns a Queue rooted at the supplied path. Tests use this to redirect into a tmpdir.
func (*Queue) Add ¶
Add appends a new pending item. id is auto-generated when empty. Returns the persisted Item (with id + created_at filled).
func (*Queue) Claim ¶
Claim returns the highest-priority pending item, marks it in_progress, and persists. ok=false (zero Item, nil err) when the queue has no pending items — the agent's signal to stop the loop.
Selection order: highest Priority first, then earliest CreatedAt. Ties broken by lexicographic ID for determinism in tests.
func (*Queue) Complete ¶
Complete marks the named item done. Idempotent: completing an already-done item returns a typed error so the caller can decide whether to ignore it. Unknown id returns ErrNotFound.
func (*Queue) List ¶
List returns every item filtered by status. Pass empty string to return all. Order: pending first (priority/created), then in_progress, then done/skipped.
Source Files