agents

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: Apache-2.0 Imports: 17 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 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 Check

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

Check reports what setup would act on, without changing anything, as report does.

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 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 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 Setup

func Setup(ctx context.Context, env Env, o Options) 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, and what to do next. It fails 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.

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.

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 Block

type Block struct {
	State BlockState
	// 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"
)

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 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 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 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
	// NotRepo: setup runs in a folder that isn't an anfra repo, so it leaves its
	// AGENTS.md alone, and the report says so.
	NotRepo bool
	Out     io.Writer
}

Options are what setup acts on.

Jump to

Keyboard shortcuts

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