plugin

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 14, 2025 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package plugin provides support for loading and using Claude Code-style plugins.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotACommand is returned when input doesn't start with a slash command.
	ErrNotACommand = errors.New("input is not a slash command")
	// ErrCommandNotFound is returned when the command doesn't exist in the plugin.
	ErrCommandNotFound = errors.New("command not found")
)

Functions

func ParseCommandInput 

func ParseCommandInput(input string) (cmdName, arguments string)

ParseCommandInput parses a potential command input and returns the command name and arguments. Returns empty strings if the input is not a command.

Types

type Agent 

type Agent struct {
	Name        string   // Derived from filename
	Description string   // From frontmatter
	Tools       []string // Tools this agent can use
	Content     string   // Markdown content (agent instructions)
	FilePath    string   // Original file path
}

Agent represents a subagent defined in a plugin.

func ParseAgent 

func ParseAgent(path string) (*Agent, error)

ParseAgent parses an agent markdown file.

func (*Agent) FilterTools 

func (a *Agent) FilterTools(tools []llm.Tool) []llm.Tool

FilterTools filters a list of tools to only include those allowed by this agent. If the agent has no tool restrictions, all tools are returned.

func (*Agent) NewRunner 

func (a *Agent) NewRunner(opts ...AgentOption) *AgentRunner

NewRunner creates a new AgentRunner for this agent. The runner maintains conversation history across multiple Run() calls.

func (*Agent) ToOption 

func (a *Agent) ToOption() llm.Option

ToOption converts an Agent to an llm.Option. This adds the agent's system message to the LLM call.

func (*Agent) ToSystemMessage 

func (a *Agent) ToSystemMessage() string

ToSystemMessage converts an Agent to a system message string. This includes the agent's role, capabilities, and instructions.

type AgentContext 

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

AgentContext maintains conversation history and state for an agent. It provides thread-safe access to conversation history and arbitrary state storage. Contexts can have parent contexts for inheritance (e.g., sub-agents inheriting from parent).

func NewAgentContext 

func NewAgentContext() *AgentContext

NewAgentContext creates a new empty context.

func (*AgentContext) AddMessage 

func (c *AgentContext) AddMessage(msg llm.Message)

AddMessage adds a message to the conversation history.

func (*AgentContext) AddMessages 

func (c *AgentContext) AddMessages(msgs ...llm.Message)

AddMessages adds multiple messages to the conversation history.

func (*AgentContext) Clear 

func (c *AgentContext) Clear()

Clear resets both conversation history and state. Note: This does not affect the parent context.

func (*AgentContext) ClearHistory 

func (c *AgentContext) ClearHistory()

ClearHistory resets only the conversation history, keeping state.

func (*AgentContext) ClearState 

func (c *AgentContext) ClearState()

ClearState resets only the state, keeping conversation history.

func (*AgentContext) Clone 

func (c *AgentContext) Clone() *AgentContext

Clone creates a deep copy of this context including history and state. The clone does not share the same parent reference.

func (*AgentContext) DeleteState 

func (c *AgentContext) DeleteState(key string)

DeleteState removes a value from the context. Note: This only removes from this context, not from parent contexts.

func (*AgentContext) GetState 

func (c *AgentContext) GetState(key string) (any, bool)

GetState retrieves a value from the context. If the key is not found in this context, it checks the parent context recursively. Returns the value and true if found, or nil and false if not found.

func (*AgentContext) HasState 

func (c *AgentContext) HasState(key string) bool

HasState checks if a key exists in this context or its parents.

func (*AgentContext) History 

func (c *AgentContext) History() []llm.Message

History returns a copy of the conversation history.

func (*AgentContext) HistoryLen 

func (c *AgentContext) HistoryLen() int

HistoryLen returns the number of messages in the history.

func (*AgentContext) LastMessage 

func (c *AgentContext) LastMessage() *llm.Message

LastMessage returns the last message in the history, or nil if empty.

func (*AgentContext) LastNMessages 

func (c *AgentContext) LastNMessages(n int) []llm.Message

LastNMessages returns the last n messages from history. If n is greater than history length, returns all messages.

func (*AgentContext) NewChildContext 

func (c *AgentContext) NewChildContext() *AgentContext

NewChildContext creates a child context that inherits state from this context. The child has its own history but can access parent's state through GetState.

func (*AgentContext) Parent 

func (c *AgentContext) Parent() *AgentContext

Parent returns the parent context, or nil if this is a root context.

func (*AgentContext) SetParent 

func (c *AgentContext) SetParent(parent *AgentContext)

SetParent sets the parent context.

func (*AgentContext) SetState 

func (c *AgentContext) SetState(key string, value any)

SetState stores a value in the context with the given key.

func (*AgentContext) StateKeys 

func (c *AgentContext) StateKeys() []string

StateKeys returns all keys in this context (not including parent keys).

type AgentIndex 

type AgentIndex struct {
	Name        string
	Description string
	Tools       []string
}

AgentIndex represents an agent's metadata for progressive disclosure.

type AgentOption 

type AgentOption func(*AgentRunner)

AgentOption configures an AgentRunner.

func WithAgentContext 

func WithAgentContext(ctx *AgentContext) AgentOption

WithAgentContext sets an existing context for the runner. This allows sharing context between agents or continuing from a previous state.

func WithAgentLLMOptions 

func WithAgentLLMOptions(opts ...llm.Option) AgentOption

WithAgentLLMOptions sets additional llm.Options to apply on every Run() call. This allows passing options like WithTopP, WithTopK, WithSeed, WithStopSequences, or additional WithSystemMessage to the agent.

Example: 

runner := agent.NewRunner(
    plugin.WithAgentProvider("anthropic"),
    plugin.WithAgentModel("claude-sonnet-4-5-20250929"),
    plugin.WithAgentLLMOptions(
        llm.WithTopP(0.9),
        llm.WithSystemMessage(p.SkillsIndexSystemMessage()),
    ),
)

func WithAgentMaxTokens 

func WithAgentMaxTokens(n int) AgentOption

WithAgentMaxTokens sets the max tokens for the agent.

func WithAgentModel 

func WithAgentModel(model string) AgentOption

WithAgentModel sets the model for the agent runner.

func WithAgentProvider 

func WithAgentProvider(name string) AgentOption

WithAgentProvider sets the provider for the agent runner.

func WithAgentTemperature 

func WithAgentTemperature(t float64) AgentOption

WithAgentTemperature sets the temperature for the agent.

func WithAgentTools 

func WithAgentTools(tools ...llm.Tool) AgentOption

WithAgentTools provides tools that the agent can use. Only tools listed in the agent's Tools field will actually be available.

type AgentRunner 

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

AgentRunner provides methods to run an agent as an independent LLM call. It maintains conversation history across multiple Run() calls via AgentContext.

func (*AgentRunner) Agent 

func (r *AgentRunner) Agent() *Agent

Agent returns the underlying agent.

func (*AgentRunner) ClearContext 

func (r *AgentRunner) ClearContext()

ClearContext resets the runner's context, clearing all conversation history and state.

func (*AgentRunner) ClearHistory 

func (r *AgentRunner) ClearHistory()

ClearHistory resets only the conversation history, keeping state.

func (*AgentRunner) Context 

func (r *AgentRunner) Context() *AgentContext

Context returns the runner's context for accessing conversation history and state.

func (*AgentRunner) FilteredTools 

func (r *AgentRunner) FilteredTools() []llm.Tool

FilteredTools returns the tools available to this agent runner.

func (*AgentRunner) Run 

func (r *AgentRunner) Run(ctx context.Context, task string, runOpts ...RunOption) (llm.Response[string], error)

Run executes the agent with a task and returns the response. Conversation history is maintained in the runner's context, allowing multi-turn conversations across multiple Run() calls.

Optional RunOption arguments can be passed to customize this specific call: 

resp, _ := runner.Run(ctx, "Help me",
    plugin.WithRunSystemMessage("Additional context for this call"),
    plugin.WithRunLLMOptions(llm.WithTopP(0.9)),
)

func (*AgentRunner) RunWithMessages 

func (r *AgentRunner) RunWithMessages(ctx context.Context, messages []llm.Message, runOpts ...RunOption) (llm.Response[string], error)

RunWithMessages executes the agent with custom messages appended to the context history. The provided messages are added to the existing context history before making the call. Optional RunOption arguments can be passed to customize this specific call.

type Author 

type Author struct {
	Name  string `json:"name"`
	Email string `json:"email,omitempty"`
	URL   string `json:"url,omitempty"`
}

Author represents plugin author information.

type Command 

type Command struct {
	Name        string // Derived from filename (e.g., "hello" from "hello.md")
	Description string // From frontmatter
	Content     string // Markdown content (the prompt)
	FilePath    string // Original file path
}

Command represents a slash command defined in a plugin.

func ParseCommand 

func ParseCommand(path string) (*Command, error)

ParseCommand parses a command markdown file.

func (*Command) ToOption 

func (c *Command) ToOption() llm.Option

ToOption converts a Command to an llm.Option. This adds the command's content as system message to the LLM call.

func (*Command) ToOptionWithArgs 

func (c *Command) ToOptionWithArgs(arguments string) llm.Option

ToOptionWithArgs converts a Command to an llm.Option with argument substitution. The $ARGUMENTS placeholder in the command content is replaced with the provided arguments.

func (*Command) ToSystemMessage 

func (c *Command) ToSystemMessage() string

ToSystemMessage converts a Command to a system message string. This includes the command description and instructions.

type CommandIndex 

type CommandIndex struct {
	Name        string
	Description string
}

CommandIndex represents a command's metadata for progressive disclosure.

type ExpandedCommand 

type ExpandedCommand struct {
	Command       *Command // The original command
	SystemMessage string   // Command content with $ARGUMENTS replaced
	UserMessage   string   // The arguments or original input
	Arguments     string   // Extracted arguments after command name
}

ExpandedCommand represents an expanded command ready for LLM call.

func (*ExpandedCommand) ToOption 

func (e *ExpandedCommand) ToOption() llm.Option

ToOption converts an ExpandedCommand to an llm.Option. This adds the expanded command's system message to the LLM call.

type MCPServerConfig 

type MCPServerConfig struct {
	Command string            `json:"command"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
}

MCPServerConfig represents an MCP server configuration.

type Plugin 

type Plugin struct {
	// Metadata from plugin.json
	Name        string
	Description string
	Version     string
	Author      Author

	// Components
	Commands []Command
	Agents   []Agent
	Skills   []Skill

	// MCP servers configuration
	MCPServers map[string]MCPServerConfig

	// Root path of the plugin
	RootPath string
}

Plugin represents a loaded Claude Code-style plugin.

func Load 

func Load(path string) (*Plugin, error)

Load loads a Claude Code-style plugin from the given path. The path should point to the plugin root directory containing .claude-plugin/plugin.json.

func (*Plugin) AgentsIndex 

func (p *Plugin) AgentsIndex() []AgentIndex

AgentsIndex returns metadata for all agents in the plugin.

func (*Plugin) AgentsIndexSystemMessage 

func (p *Plugin) AgentsIndexSystemMessage() string

AgentsIndexSystemMessage returns a compact agents list for system prompt.

Format: 

<available_agents>
- agent-name: Description (tools: tool1, tool2)
</available_agents>

func (*Plugin) AgentsSystemMessage 

func (p *Plugin) AgentsSystemMessage() string

AgentsSystemMessage returns a system message with only the agents.

func (*Plugin) CommandsIndex 

func (p *Plugin) CommandsIndex() []CommandIndex

CommandsIndex returns metadata for all commands in the plugin.

func (*Plugin) CommandsIndexSystemMessage 

func (p *Plugin) CommandsIndexSystemMessage() string

CommandsIndexSystemMessage returns a compact commands list for system prompt.

Format: 

<available_commands>
- /command-name: Description of the command
</available_commands>

func (*Plugin) CommandsSystemMessage 

func (p *Plugin) CommandsSystemMessage() string

CommandsSystemMessage returns a system message with only the commands.

func (*Plugin) ExpandCommand 

func (p *Plugin) ExpandCommand(input string) (*ExpandedCommand, error)

ExpandCommand expands a command from user input. Input: "/greet John" → finds "greet" command, extracts "John" as argument. The command's Content is used as SystemMessage with $ARGUMENTS replaced.

func (*Plugin) GetAgent 

func (p *Plugin) GetAgent(name string) *Agent

GetAgent returns an agent by name, or nil if not found.

func (*Plugin) GetCommand 

func (p *Plugin) GetCommand(name string) *Command

GetCommand returns a command by name, or nil if not found.

func (*Plugin) GetSkill 

func (p *Plugin) GetSkill(name string) *Skill

GetSkill returns a skill by name, or nil if not found.

func (*Plugin) HasAgent 

func (p *Plugin) HasAgent(name string) bool

HasAgent checks if an agent with the given name exists.

func (*Plugin) HasCommand 

func (p *Plugin) HasCommand(name string) bool

HasCommand checks if a command with the given name exists.

func (*Plugin) HasSkill 

func (p *Plugin) HasSkill(name string) bool

HasSkill checks if a skill with the given name exists.

func (*Plugin) IsCommand 

func (p *Plugin) IsCommand(input string) bool

IsCommand checks if input starts with a slash command. Returns true for inputs like "/greet", "/hello world", etc.

func (*Plugin) PluginIndexSystemMessage 

func (p *Plugin) PluginIndexSystemMessage() string

PluginIndexSystemMessage returns a combined index of all plugin components. This is useful for giving the LLM an overview of available capabilities.

func (*Plugin) ProcessInput 

func (p *Plugin) ProcessInput(input string) (opt llm.Option, userMessage string, err error)

ProcessInput processes user input and returns the appropriate llm.Option. If the input is a slash command (e.g., "/greet John"), it expands the command. If the input is not a command, it returns nil and the original input.

Usage: 

opt, userMsg, err := plugin.ProcessInput("/greet John")
if err != nil { ... }
if opt != nil {
    resp, _ := llm.Call(ctx, userMsg, opt, otherOpts...)
} else {
    resp, _ := llm.Call(ctx, userMsg, otherOpts...)
}

func (*Plugin) SkillsIndex 

func (p *Plugin) SkillsIndex() []SkillIndex

SkillsIndex returns metadata for all skills in the plugin. Use this for progressive disclosure - present the list first, then load full skill content only when needed.

func (*Plugin) SkillsIndexSystemMessage 

func (p *Plugin) SkillsIndexSystemMessage() string

SkillsIndexSystemMessage returns a compact skills list for system prompt. This follows a progressive disclosure pattern (similar to Claude Code) - include only metadata in the system prompt, load full content when skill is invoked.

Format: 

<available_skills>
- skill-name: Description of the skill
</available_skills>

func (*Plugin) SkillsSystemMessage 

func (p *Plugin) SkillsSystemMessage() string

SkillsSystemMessage returns a system message with only the skills.

func (*Plugin) ToSystemMessage 

func (p *Plugin) ToSystemMessage() string

ToSystemMessage converts the entire Plugin to a comprehensive system message. This includes all commands, agents, and skills defined in the plugin.

type RunOption 

type RunOption func(*runConfig)

RunOption configures a single Run() call.

func WithRunLLMOptions 

func WithRunLLMOptions(opts ...llm.Option) RunOption

WithRunLLMOptions adds additional llm.Options for this Run() call only.

func WithRunSystemMessage 

func WithRunSystemMessage(msg string) RunOption

WithRunSystemMessage adds an additional system message for this Run() call only. This is useful for adding context-specific instructions without modifying the runner.

type Skill 

type Skill struct {
	Name        string   // Derived from directory name
	Description string   // From frontmatter
	Tools       []string // Tools this skill requires
	Content     string   // Markdown content (skill instructions)
	FilePath    string   // Original file path
}

Skill represents an agent skill defined in a plugin.

func ParseSkill 

func ParseSkill(dirPath string) (*Skill, error)

ParseSkill parses a skill from a directory containing SKILL.md.

func (*Skill) FilterTools 

func (s *Skill) FilterTools(tools []llm.Tool) []llm.Tool

FilterTools filters a list of tools to only include those required by this skill. If the skill has no tool requirements, all tools are returned. Tools are matched by name (case-insensitive prefix match).

func (*Skill) HasRequiredTools 

func (s *Skill) HasRequiredTools(tools []llm.Tool) bool

HasRequiredTools checks if all required tools are available in the provided list.

func (*Skill) MissingTools 

func (s *Skill) MissingTools(tools []llm.Tool) []string

MissingTools returns the list of required tools that are not available.

func (*Skill) ToOption 

func (s *Skill) ToOption() llm.Option

ToOption converts a Skill to an llm.Option. This adds the skill's system message to the LLM call.

func (*Skill) ToSystemMessage 

func (s *Skill) ToSystemMessage() string

ToSystemMessage converts a Skill to a system message string. This includes the skill's purpose and instructions.

type SkillIndex 

type SkillIndex struct {
	Name        string
	Description string
}

SkillIndex represents a skill's metadata for progressive disclosure. This allows presenting skill information without loading full content.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.