agents

package
v0.21.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package agents sets up the anfra skills in the coding agents on this machine (docs/designs/agent-setup.md): a plugin through the agent's own CLI where anfra knows one, a pointer to the skills repo's README for every other agent. It runs programs on this machine, so only the CLI uses it, never an op.

Index

Constants

View Source
const (
	SkillsRepo  = "holistics/anfra-skills"
	Marketplace = "anfra-skills"
	Plugin      = "anfra"
	PluginID    = Plugin + "@" + Marketplace
)

The skills, published as a plugin marketplace that Claude Code and Codex each install from.

Variables

View Source
var ErrIncomplete = errors.New("the anfra skills are not set up for every agent")

ErrIncomplete is setup leaving an agent without the skills, or the anfra block unwritten: Setup returns it with its result, as far as it got.

View Source
var Known = []Agent{
	{
		ID: "claude-code", Name: "Claude Code",
		// contains filtered or unexported fields
	},
	{
		ID: "codex", Name: "Codex",
		// contains filtered or unexported fields
	},
	{
		ID: "cursor", Name: "Cursor",
		// contains filtered or unexported fields
	},
	{
		ID: "github-copilot", Name: "GitHub Copilot",
		// contains filtered or unexported fields
	},
	{
		ID: "opencode", Name: "OpenCode",
		// contains filtered or unexported fields
	},
	{
		ID: "gemini-cli", Name: "Gemini CLI",
		// contains filtered or unexported fields
	},
	{
		ID: "antigravity", Name: "Antigravity",
		// contains filtered or unexported fields
	},
	{
		ID: "junie", Name: "Junie",
		// contains filtered or unexported fields
	},
	{
		ID: "windsurf", Name: "Windsurf",
		// contains filtered or unexported fields
	},
	{
		ID: "cline", Name: "Cline",
		// contains filtered or unexported fields
	},
	{
		ID: "warp", Name: "Warp",
		// contains filtered or unexported fields
	},
}

Known are the agents anfra knows, in the order setup reports them. Each has a section in the skills repo's README, anchored by its id; adding one here means adding its section there.

Functions

func Attention

func Attention(env Env, repoDir string) string

Attention is one line saying what of the agents' skills needs attention, and to run setup: the plugins behind, as anfra last recorded them; the copies behind and with deprecated skills, in the folders the agents read; and repoDir's AGENTS.md block ("" outside a repo). "" when nothing does. No network and no agent CLI: it is cheap enough to run after a command.

func Badge added in v0.18.0

func Badge(env Env, repoDir string) (mark, label string)

Badge is Attention as a console's badge (docs/designs/console.md): a mark and a few words, the command to run being setup's. ↑ and the latest skills when a plugin or a copy is behind; ! and how many issues when something else needs attention; ! when the agents have no skills; "" when nothing needs attention.

func Failed added in v0.15.1

func Failed(env Env, repoDir string, now time.Time) string

Failed records a failure the caller could fix (an invalid input, an unknown command or flag), off a terminal, and says what to hint in its error: "" but for the failure that makes hintAfter within hintWithin, once per streak, and only when an agent is detected and none has the skills. When the plugins have never been recorded, the hint is worded to hold either way.

func IDs

func IDs() []string

IDs are the known agents' ids.

func MarkNoticed added in v0.18.0

func MarkNoticed()

MarkNoticed records that the notice printed, now.

func Newer

func Newer(a, b string) bool

Newer reports whether version a is newer than b; false when either isn't a full version (1.2.3, without a prefix).

func Notice

func Notice(env Env, repoDir string) string

Notice is Attention, at most once a day: "" when it printed less than a day ago, or nothing needs attention. It records that it printed.

func NoticeDue added in v0.18.0

func NoticeDue() bool

NoticeDue reports whether a day has passed since the notice last printed, for one shown after a command, at most once a day.

func ParseStamp

func ParseStamp(skill []byte) (string, bool)

ParseStamp is the skills version a SKILL.md states, from its stamp; false when it has none, as a copy from before the stamp existed has none.

func ReadmeFor

func ReadmeFor(id string) string

ReadmeFor is the README's install section for an agent id: its own for a known agent, the one for any other agent otherwise, so the link always lands on a section that exists.

func RecordPlugins

func RecordPlugins(ctx context.Context, env Env)

RecordPlugins asks each agent's CLI for its plugins and keeps the answer, for the notice. Agents' CLIs start slowly, so this is for the background check and setup, never an ordinary command.

func Succeeded added in v0.15.1

func Succeeded()

Succeeded ends a streak of failures. A command that succeeds with none costs a missing file's stat.

func WriteBlock

func WriteBlock(repoDir string) (wroteBlock, wroteImport bool, err error)

WriteBlock writes the anfra block into repoDir's AGENTS.md: it adds it to the file, creating it, or replaces the block that is there. It adds the import to the repo's CLAUDE.md, when it has one. It refuses a symlink, which would write outside the repo. It says whether it wrote the block, and the import. A failure to add the import is an *ImportError, so that a caller can tell it from a failure to write the block.

Types

type Agent

type Agent struct {
	ID   string // npx skills' id: the --agent value, and the README section's anchor
	Name string
	// contains filtered or unexported fields
}

Agent is a coding agent anfra knows: how to find it on this machine, and how it gets the skills.

func Find

func Find(id string) (Agent, bool)

Find is the known agent with id.

func (Agent) Detected

func (a Agent) Detected(env Env) bool

Detected reports whether the agent is on this machine: one of its CLIs is on the PATH, or one of its folders exists.

func (Agent) InstalledPlugin

func (a Agent) InstalledPlugin(ctx context.Context, env Env) []Installed

InstalledPlugin lists the agent's installed copies of the plugin, through its CLI. Nil when anfra doesn't install into it, its CLI isn't on the PATH, or the list fails. Agents' CLIs start slowly (Claude Code's starts Node), so this is for setup and update, never an ordinary command.

func (Agent) Installs

func (a Agent) Installs() bool

Installs reports whether anfra installs the plugin into the agent itself, rather than pointing at the README.

func (Agent) README

func (a Agent) README() string

README is the skills repo's install section for the agent.

type AgentSetup added in v0.17.0

type AgentSetup struct {
	// Agent is its id, what --agent takes; not in the pretty format, as the
	// report's agents.
	Agent   string  `json:"agent" doc:"the agent, as --agent takes it" pretty:"-"`
	Name    string  `json:"name" doc:"the agent's name"`
	Outcome Outcome `` /* 195-byte string literal not displayed */
	Message string  `json:"message" doc:"what to do next: restart the agent, install its CLI, or follow the README" pretty:",truncate"`
}

AgentSetup is what setup did for one agent.

type AgentState added in v0.17.0

type AgentState struct {
	// ID is what --agent takes; not in the pretty format, where Name says
	// the same to a person, and --help lists the ids.
	ID      string        `json:"id" doc:"the agent, as --agent takes it" pretty:"-"`
	Name    string        `json:"name" doc:"the agent's name"`
	Status  AgentStatus   `` /* 174-byte string literal not displayed */
	Plugins []PluginState `json:"plugins" doc:"its plugins, installed through its CLI"`
	Copies  []string      `json:"copies" doc:"the folders it reads that hold anfra skills"`
	// InstallFrom is where to install the skills from: its README section;
	// absent when they're installed. Not in the pretty format, where a hint
	// says it, so the agents' table fits a terminal.
	InstallFrom string `json:"install_from,omitempty" doc:"a link to the instructions for installing the skills for this agent" pretty:"-"`
}

AgentState is where an agent's skills come from: the plugin, through its CLI, or copies in the folders it reads.

type AgentStatus added in v0.17.0

type AgentStatus string

AgentStatus is whether an agent has the anfra skills.

const (
	AgentInstalled    AgentStatus = "installed"
	AgentNotInstalled AgentStatus = "not-installed"
)

type AgentsMDSetup added in v0.17.0

type AgentsMDSetup struct {
	WroteBlock  bool   `json:"wrote_block" doc:"whether it wrote the anfra block"`
	WroteImport bool   `json:"wrote_import" doc:"whether it wrote @AGENTS.md in CLAUDE.md"`
	Message     string `json:"message,omitempty" doc:"why setup couldn't write the anfra block or @AGENTS.md in CLAUDE.md"`
	// contains filtered or unexported fields
}

AgentsMDSetup is what setup wrote of the anfra block.

type AgentsMDState added in v0.17.0

type AgentsMDState struct {
	Block    BlockState    `` /* 136-byte string literal not displayed */
	ClaudeMD ClaudeMDState `` /* 231-byte string literal not displayed */
	Message  string        `json:"message,omitempty" doc:"why AGENTS.md or CLAUDE.md can't be read"`
}

AgentsMDState is the repo's anfra block in AGENTS.md.

type Block

type Block struct {
	State BlockState
	// HasClaudeMD: the repo has a CLAUDE.md.
	HasClaudeMD bool
	// NoImport: the repo has a CLAUDE.md, which doesn't import AGENTS.md.
	NoImport bool
}

Block is the state of a repo's anfra block in AGENTS.md, and of the import in its CLAUDE.md.

func CheckBlock

func CheckBlock(repoDir string) (Block, error)

CheckBlock reports the anfra block in repoDir's AGENTS.md, and the import in its CLAUDE.md, when it has one.

type BlockState

type BlockState string

BlockState is the state of the anfra block itself.

const (
	BlockMissing  BlockState = "missing"
	BlockOutdated BlockState = "outdated" // other than what this anfra writes
	BlockUpToDate BlockState = "up-to-date"
)
const BlockUnreadable BlockState = "unreadable"

BlockUnreadable: AGENTS.md or CLAUDE.md can't be read as a file of the repo.

type CheckResult added in v0.17.0

type CheckResult struct {
	Message string `json:"message" doc:"the outcome, in a sentence"`
	Report  `json:",inline"`
	Hints   []string `json:"hints,omitempty" doc:"what to do next, if any"`
}

CheckResult is `agent setup check`'s result: the Report, between its message, the outcome, and its hints, what to do next (docs/designs/commands-and-api.md#cli-output).

func Check

func Check(ctx context.Context, env Env, o Options) (CheckResult, error)

Check reports the state of the agents' skills, as setup would find them, and changes nothing.

type ClaudeMDState added in v0.17.0

type ClaudeMDState string

ClaudeMDState is a repo's CLAUDE.md, against the import of AGENTS.md Claude Code needs to read it.

const (
	ClaudeMDImported    ClaudeMDState = "imported"
	ClaudeMDNotImported ClaudeMDState = "not-imported"
	ClaudeMDAbsent      ClaudeMDState = "absent"
)

type Copy

type Copy struct {
	Dir string // the skills folder, as shown: ~/… or relative to the repo

	// Versions are its skills by the version they state: "" for those with no
	// stamp. A copy installed whole has one.
	Versions map[string][]string
	// OldNames: it has skills of the names from before the prefix, which an
	// agent loads next to the new ones until they are removed.
	OldNames bool
	// contains filtered or unexported fields
}

Copy is a copy of the skills in a folder anfra knows.

func Copies

func Copies(env Env, repoDir string) []Copy

Copies are the copies of the skills in the folders the known agents read, under the user's home and under repoDir ("" for none), in that order. A copy in any other folder, or in an agent's plugin cache, isn't found.

func (Copy) Oldest

func (c Copy) Oldest() string

Oldest is the copy's oldest skills version: "" when a skill has no stamp, which is older than any.

type CopyState added in v0.17.0

type CopyState struct {
	Dir             string          `json:"dir" doc:"the folder"`
	Status          string          `` /* 410-byte string literal not displayed */
	Versions        []SkillsVersion `json:"versions" doc:"its skills by version, oldest first"`
	DeprecatedNames bool            `` /* 126-byte string literal not displayed */
}

CopyState is a folder of copies of the skills against the latest.

type Env

type Env struct {
	Home     string                       // the user's home folder
	Getenv   func(string) string          // the environment
	LookPath func(string) (string, error) // finds a CLI on the PATH
	// Run runs a command where the user sees it, and can answer what it asks.
	Run func(ctx context.Context, bin string, args ...string) error
	// Output runs a command and returns what it prints.
	Output func(ctx context.Context, bin string, args ...string) ([]byte, error)
}

Env is what the package touches outside this process, swapped in tests.

func System

func System() Env

System is this machine's Env.

type ImportError added in v0.19.0

type ImportError struct{ Err error }

ImportError is WriteBlock failing on CLAUDE.md, after AGENTS.md is done, so that setup doesn't report the block as unwritten. Its text is its cause's.

func (*ImportError) Error added in v0.19.0

func (e *ImportError) Error() string

func (*ImportError) Unwrap added in v0.19.0

func (e *ImportError) Unwrap() error

type Installed

type Installed struct {
	Version string `json:"version"`
	Scope   string `json:"scope"`
}

Installed is an installed copy of the plugin: its version, and the scope the agent reports it at (user, project, …). anfra installs for the user only.

type LatestSkills added in v0.17.0

type LatestSkills struct {
	Latest    *string    `json:"latest" doc:"the latest anfra skills version. Null when it isn't known."`
	CheckedAt *time.Time `json:"checked_at" doc:"when anfra last checked for the latest version" pretty:",moment"`
}

LatestSkills is the latest anfra skills version, from the background check, as `anfra version` names it; null until the check has run.

type Options

type Options struct {
	// Agents are the ids named with --agent; none: the agents detected.
	Agents []string
	// RepoDir is the anfra repo setup runs in, whose AGENTS.md gets the anfra
	// block, and whose copies of the skills the check looks for too; "" outside
	// one.
	RepoDir string
	// Progress is where to say, for a person, what setup is doing and what to
	// do next; nil says nothing. The result says what it did.
	Progress io.Writer
}

Options are what setup acts on.

type Outcome added in v0.17.0

type Outcome string

Outcome is what setup did for an agent.

const (
	OutcomeInstalled        Outcome = "installed"         // installed or updated
	OutcomeFailed           Outcome = "failed"            // an install step failed
	OutcomeCLIMissing       Outcome = "cli_missing"       // not tried: its CLI isn't on the PATH
	OutcomeInstructionsOnly Outcome = "instructions_only" // anfra doesn't install for it: the README says how
)

type PluginState added in v0.17.0

type PluginState struct {
	Scope   string `json:"scope" doc:"the scope the agent installed the plugin at, such as \"user\" or \"project\""`
	Version string `json:"version" doc:"the plugin's skills version"`
	Status  string `` /* 226-byte string literal not displayed */
}

PluginState is an installed plugin against the latest skills.

type Report added in v0.17.0

type Report struct {
	Skills   LatestSkills   `json:"skills" doc:"the latest anfra skills version"`
	Agents   []AgentState   `json:"agents" doc:"each agent, and where its skills come from"`
	Copies   []CopyState    `json:"copies" doc:"each folder of copies of the skills"`
	AgentsMD *AgentsMDState `json:"agents_md" doc:"the repo's anfra block in AGENTS.md. Null outside an anfra repo." pretty:"AGENTS.md"`
}

Report is the state of the agents' skills: what `agent setup check` answers, and setup with it, as setup leaves it.

type SetupActions added in v0.17.0

type SetupActions struct {
	Agents   []AgentSetup   `json:"agents" doc:"what setup did for each agent"`
	AgentsMD *AgentsMDSetup `json:"agents_md" doc:"what setup wrote to AGENTS.md and CLAUDE.md. Null outside an anfra repo." pretty:"AGENTS.md"`
}

SetupActions are what setup did.

type SetupResult added in v0.17.0

type SetupResult struct {
	Message string       `json:"message" doc:"the outcome, in a sentence"`
	Setup   SetupActions `json:"setup" doc:"what setup did"`
	Report  `json:",inline"`
	Hints   []string `json:"hints,omitempty" doc:"what to do next, if any"`
}

SetupResult is setup's result: what it did, then the Report as it leaves things (docs/designs/commands-and-api.md#new-state-as-output), between its message and its hints.

func Setup

func Setup(ctx context.Context, env Env, o Options) (SetupResult, error)

Setup installs the plugin into each agent anfra installs into, and writes the AGENTS.md block in an anfra repo, then reports the state it leaves, as Check does. It fails, with ErrIncomplete, when an install step failed or an agent named with --agent ends up without the plugin: an agent that was only detected doesn't fail it, as anyone with a second agent's folder would see setup fail on every run.

type SkillsVersion added in v0.17.0

type SkillsVersion struct {
	Version *string  `json:"version" doc:"the version. Null for skills with no version stamp."`
	Skills  []string `json:"skills" doc:"the names of the skills at this version"`
}

SkillsVersion is the skills of a copy at one version, oldest first.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL