agentplug

Documentation

Overview

Package agentplug runs the agents plugins add: a module, named by a plugin's package.json magpie.agent, that says where an agent magpie has no wiring of its own keeps its model, and what else to write there for it to use magpie's gateway. internal/agent makes each one an Agent.

A module exports

export const agent = {
  id: "aider", name: "Aider",
  config: "~/.aider.conf.yml", // the file magpie edits
  model: "model",              // the key path of the model in it
  prefix: "openai/",           // what the agent wants before the id
}
export function connect({ gateway, model, models }) {
  return { "openai-api-base": gateway.v1, "openai-api-key": gateway.key }
}

and it runs in moejs in magpie's own process, as gateway middleware does: there is no Node here, so a package it imports is bundled into it.

An agent whose model is picked in the agent itself (Raycast's own picker, among the models connect writes) leaves model out: it is connect only, a switch on the Agents page as an app whose one setting is magpie as its provider is, and connect is called without a model (#2374).

The agent export may also say where its agent reads what magpie's Library gives (internal/library): an instructions file, an MCP file in one of MCPFormats, and a skills folder; each is optional.

library: {
  instructions: "~/.aider/AGENTS.md",
  mcp: "~/.aider/mcp.json", mcpFormat: "claude",
  skills: "~/.aider/skills",
}

Index

• Variables
• func Reload()
• type Agent
  • func Compile(spec, file string) (*Agent, error)
  • func List() ([]*Agent, map[string]string)
  • func (a *Agent) Connect(in map[string]any) (map[string]any, error)
• type Desc
• type Places

Variables

var Formats = map[string]string{
	".json": "json", ".jsonc": "json",
	".yaml": "yaml", ".yml": "yaml",
	".env": "env",
}

Formats are the config files an agent plugin's file may be, by the name its agent.format gives or its extension says.

var MCPFormats = []string{
	"alma", "antigravity", "claude", "cline", "codex", "commandcode", "copilot",
	"crush", "cursor", "devin", "gemini", "goose", "grok", "hermes", "kimi",
	"omp", "opencode", "zed",
}

MCPFormats are the MCP files an agent plugin's agent may keep, each named for the agent whose file it is written as: "claude" is {"mcpServers": {name: {type, command, args, env, url, headers}}}.

Functions

func Reload

func Reload()

Reload drops the agents loaded, so the next List loads them again.

Types

type Agent

type Agent struct {
	Spec string // the plugin's spec in plugins.json
	File string
	Desc Desc
	// contains filtered or unexported fields
}

Agent is one plugin's agent, compiled.

func Compile

func Compile(spec, file string) (*Agent, error)

Compile compiles the agent module in file, of the plugin spec, and checks what its agent export says.

func List

func List() ([]*Agent, map[string]string)

List is the agents the plugins switched on add, in plugins.json's order, and why any didn't load, by plugin spec. It is loaded again when plugins.json or a module's file changed, which is looked at once a second.

func (*Agent) Connect

func (a *Agent) Connect(in map[string]any) (map[string]any, error)

Connect is what the module's connect returns for in: the keys to write beside the model, by key path. A module without connect writes none.

type Desc

type Desc struct {
	ID     string   `json:"id"`
	Name   string   `json:"name"`
	Config string   `json:"config"`
	Format string   `json:"format"`
	Model  string   `json:"model"`
	Prefix string   `json:"prefix"`
	Bin    string   `json:"bin"`
	Dir    string   `json:"dir"`
	UA     []string `json:"ua"`
	Icon   string   `json:"icon"`
	// Notice is advice shown after a change, as a built-in agent's is
	// (an agent that reads its config at start-up needs a restart)
	Notice string `json:"notice"`
	// Library is where the agent reads the Library's instructions, MCP
	// servers and skills
	Library Places `json:"library"`
}

Desc is what a module's agent export says.

type Places

type Places struct {
	Instructions string `json:"instructions"`
	MCP          string `json:"mcp"`
	// MCPFormat is how its MCP file lists servers: one of MCPFormats
	MCPFormat string `json:"mcpFormat"`
	Skills    string `json:"skills"`
}

Places are where an agent reads what the Library gives it, each a path as Config is (~ and $VAR expanded); an empty one is a thing it isn't given.