claudetool

package
v0.448.972577335 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package claudetool provides tools for Claude AI models.

When adding, removing, or modifying tools in this package, remember to update the tool display template in termui/termui.go to ensure proper tool output formatting.

Index

Constants

View Source 
const (
	EnableBashToolJITInstall = true
	NoBashToolJITInstall     = false

	DefaultFastTimeout = 30 * time.Second
	DefaultSlowTimeout = 15 * time.Minute
)
View Source 
const (
	PatchName            = "patch"
	PatchBaseDescription = `` /* 312-byte string literal not displayed */

	PatchClipboardDescription = `` /* 899-byte string literal not displayed */

	PatchUsageNotes = `` /* 406-byte string literal not displayed */

	// If you modify this, update the termui template for prettier rendering.
	PatchStandardInputSchema = `` /* 921-byte string literal not displayed */

	PatchStandardSimplifiedSchema = `` /* 777-byte string literal not displayed */

	PatchClipboardInputSchema = `` /* 1810-byte string literal not displayed */

)

Variables

This section is empty.

Functions

func FindRepoRoot 

func FindRepoRoot(wd string) (string, error)

FindRepoRoot attempts to find the git repository root from the current directory

func IsAutogeneratedGoFile 

func IsAutogeneratedGoFile(buf []byte) bool

IsAutogeneratedGoFile reports whether a Go file has markers indicating it was autogenerated.

func SessionID 

func SessionID(ctx context.Context) string

func WithSessionID 

func WithSessionID(ctx context.Context, sessionID string) context.Context

func WithWorkingDir 

func WithWorkingDir(ctx context.Context, wd string) context.Context

func WorkingDir 

func WorkingDir(ctx context.Context) string

Types

type A2ADispatchDisplayData added in v0.418.943057774 

type A2ADispatchDisplayData struct {
	URL       string `json:"url"`
	TaskID    string `json:"task_id"`
	ContextID string `json:"context_id"`
	State     string `json:"state"`
}

A2ADispatchDisplayData is the UI-side display payload.

type A2ADispatchTool added in v0.418.943057774 

type A2ADispatchTool struct{}

A2ADispatchTool delegates a task to a remote A2A-speaking agent.

func (*A2ADispatchTool) Run added in v0.418.943057774 

func (a *A2ADispatchTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

func (*A2ADispatchTool) Tool added in v0.418.943057774 

func (a *A2ADispatchTool) Tool() *llm.Tool

Tool returns the llm.Tool wrapper.

type BashDisplayData 

type BashDisplayData struct {
	WorkingDir string `json:"workingDir"`
}

BashDisplayData is the display data sent to the UI for bash tool results.

type BashTool 

type BashTool struct {
	// CheckPermission is called before running any command, if set
	CheckPermission PermissionCallback
	// EnableJITInstall enables just-in-time tool installation for missing commands
	EnableJITInstall bool
	// Timeouts holds the configurable timeout values (uses defaults if nil)
	Timeouts *Timeouts
	// WorkingDir is the shared mutable working directory.
	WorkingDir *MutableWorkingDir
	// LLMProvider provides access to LLM services for tool validation
	LLMProvider LLMServiceProvider
	// ConversationID is the ID of the conversation this tool belongs to.
	// It is exposed to invoked commands via PERCY_CONVERSATION_ID.
	ConversationID string
}

BashTool specifies an llm.Tool for executing shell commands.

func (*BashTool) Run 

func (b *BashTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

func (*BashTool) Tool 

func (b *BashTool) Tool() *llm.Tool

Tool returns an llm.Tool based on b.

type ChangeDirTool 

type ChangeDirTool struct {
	// WorkingDir is the shared mutable working directory.
	WorkingDir *MutableWorkingDir
	// OnChange is called after the working directory changes successfully.
	// This can be used to persist the change to a database.
	OnChange func(newDir string)
}

ChangeDirTool changes the working directory for bash commands.

func (*ChangeDirTool) Run 

func (c *ChangeDirTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

Run executes the change_dir tool.

func (*ChangeDirTool) Tool 

func (c *ChangeDirTool) Tool() *llm.Tool

Tool returns an llm.Tool for changing directories.

type EmbeddedFile 

type EmbeddedFile struct {
	Name    string `json:"name"`
	Path    string `json:"path"`
	Content string `json:"content"`
	Type    string `json:"type"` // "json", "css", "js", "text"
}

EmbeddedFile represents a file bundled with the HTML.

type KeywordTool 

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

KeywordTool provides keyword search functionality

func NewKeywordTool 

func NewKeywordTool(provider LLMServiceProvider) *KeywordTool

NewKeywordTool creates a new keyword tool with the given LLM provider

func NewKeywordToolWithWorkingDir 

func NewKeywordToolWithWorkingDir(provider LLMServiceProvider, wd *MutableWorkingDir) *KeywordTool

NewKeywordToolWithWorkingDir creates a new keyword tool with the given LLM provider and shared working directory

func (*KeywordTool) Tool 

func (k *KeywordTool) Tool() *llm.Tool

Tool returns the LLM tool definition

type LLMServiceProvider 

type LLMServiceProvider interface {
	GetService(modelID string) (llm.Service, error)
	GetAvailableModels() []string
}

LLMServiceProvider defines the interface for getting LLM services

type MutableWorkingDir 

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

WorkingDir is a thread-safe mutable working directory.

func NewMutableWorkingDir 

func NewMutableWorkingDir(dir string) *MutableWorkingDir

NewMutableWorkingDir creates a new MutableWorkingDir with the given initial directory.

func (*MutableWorkingDir) Get 

func (w *MutableWorkingDir) Get() string

Get returns the current working directory.

func (*MutableWorkingDir) Set 

func (w *MutableWorkingDir) Set(dir string)

Set updates the working directory.

type OrchestrateOptions added in v0.442.945520720 

type OrchestrateOptions struct {
	PlannerModel   string
	BuilderModel   string
	VerifierModel  string
	MaxConcurrency int
	SkipVerify     bool
}

OrchestrateOptions controls per-stage model selection, concurrency, and whether the verifier stage runs.

type OrchestrateRunner added in v0.442.945520720 

type OrchestrateRunner interface {
	RunOrchestration(ctx context.Context, parentConversationID, cwd, goal string, opts OrchestrateOptions) (string, error)
}

OrchestrateRunner runs a planner->builders->verifier pipeline. It is implemented by the server package to avoid an import cycle. It returns a human-readable summary of the run.

type OrchestrateTool added in v0.442.945520720 

type OrchestrateTool struct {
	ParentConversationID string
	WorkingDir           *MutableWorkingDir
	Runner               OrchestrateRunner
}

OrchestrateTool dispatches a goal through the planner->builders->verifier pipeline, each stage running in its own subagent conversation and model.

func (*OrchestrateTool) Run added in v0.442.945520720 

func (o *OrchestrateTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

func (*OrchestrateTool) Tool added in v0.442.945520720 

func (o *OrchestrateTool) Tool() *llm.Tool

Tool returns an llm.Tool for the orchestrate functionality.

type OutputIframeDisplay 

type OutputIframeDisplay struct {
	Type     string         `json:"type"`
	HTML     string         `json:"html"`
	Title    string         `json:"title,omitempty"`
	Filename string         `json:"filename,omitempty"`
	Files    []EmbeddedFile `json:"files,omitempty"`
}

OutputIframeDisplay is the data passed to the UI for rendering.

type OutputIframeTool 

type OutputIframeTool struct {
	WorkingDir *MutableWorkingDir
}

OutputIframeTool displays sandboxed HTML content to the user. It requires a MutableWorkingDir to resolve relative file paths.

func (*OutputIframeTool) Run 

func (t *OutputIframeTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

func (*OutputIframeTool) Tool 

func (t *OutputIframeTool) Tool() *llm.Tool

type PatchCallback 

type PatchCallback func(input PatchInput, output llm.ToolOut) llm.ToolOut

PatchCallback defines the signature for patch tool callbacks. It runs after the patch tool has executed. It receives the patch input and the tool output, and returns a new, possibly altered tool output.

type PatchDisplayData 

type PatchDisplayData struct {
	Path       string `json:"path"`
	OldContent string `json:"oldContent"`
	NewContent string `json:"newContent"`
	Diff       string `json:"diff"`
}

PatchDisplayData is the structured data sent to the UI for display.

type PatchInput 

type PatchInput struct {
	Path    string         `json:"path"`
	Patches []PatchRequest `json:"patches"`
}

PatchInput represents the input structure for patch operations.

type PatchInputOne 

type PatchInputOne struct {
	Path    string        `json:"path"`
	Patches *PatchRequest `json:"patches"`
}

PatchInputOne is a simplified version of PatchInput for single patch operations.

type PatchInputOneSingular 

type PatchInputOneSingular struct {
	Path  string        `json:"path"`
	Patch *PatchRequest `json:"patch"`
}

PatchInputOneSingular is PatchInputOne with a better name for the singular case.

type PatchInputOneString 

type PatchInputOneString struct {
	Path    string `json:"path"`
	Patches string `json:"patches"` // contains Patches as a JSON string 🤦
}

type PatchRequest 

type PatchRequest struct {
	Operation     string    `json:"operation"`
	OldText       string    `json:"oldText,omitempty"`
	NewText       string    `json:"newText,omitempty"`
	ToClipboard   string    `json:"toClipboard,omitempty"`
	FromClipboard string    `json:"fromClipboard,omitempty"`
	Reindent      *Reindent `json:"reindent,omitempty"`
}

PatchRequest represents a single patch operation.

type PatchTool 

type PatchTool struct {
	Callback PatchCallback // may be nil
	// WorkingDir is the shared mutable working directory.
	WorkingDir *MutableWorkingDir
	// Simplified indicates whether to use the simplified input schema.
	// Helpful for weaker models.
	Simplified bool
	// ClipboardEnabled controls whether clipboard functionality is enabled.
	// Ignored if Simplified is true.
	// NB: The actual implementation of the patch tool is unchanged,
	// this flag merely extends the description and input schema to include the clipboard operations.
	ClipboardEnabled bool
	// contains filtered or unexported fields
}

PatchTool specifies an llm.Tool for patching files. PatchTools are not concurrency-safe.

func (*PatchTool) Run 

func (p *PatchTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

Run implements the patch tool logic.

func (*PatchTool) Tool 

func (p *PatchTool) Tool() *llm.Tool

Tool returns an llm.Tool based on p.

type PermissionCallback 

type PermissionCallback func(command string) error

PermissionCallback is a function type for checking if a command is allowed to run

type ReadFileTool added in v0.308.925742072 

type ReadFileTool struct {
	WorkingDir *MutableWorkingDir
}

ReadFileTool reads a file and returns its contents with line numbers.

func (*ReadFileTool) Run added in v0.308.925742072 

func (r *ReadFileTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

Run executes the read_file tool.

func (*ReadFileTool) Tool added in v0.308.925742072 

func (r *ReadFileTool) Tool() *llm.Tool

Tool returns an llm.Tool for reading files.

type Reindent 

type Reindent struct {
	// TODO: it might be nice to make this more flexible,
	// so it can e.g. strip all whitespace,
	// or strip the prefix only on lines where it is present,
	// or strip based on a regex.
	Strip string `json:"strip,omitempty"`
	Add   string `json:"add,omitempty"`
}

Reindent represents indentation adjustment configuration.

type RequestToolsTool added in v0.373.915512555 

type RequestToolsTool struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

RequestToolsTool is a meta-tool that lets the LLM activate deferred tool categories on demand.

func NewRequestToolsTool added in v0.373.915512555 

func NewRequestToolsTool(deferred []*llm.Tool) *RequestToolsTool

NewRequestToolsTool creates a new RequestToolsTool with the given deferred tools.

func (*RequestToolsTool) AllActivated added in v0.373.915512555 

func (r *RequestToolsTool) AllActivated() bool

AllActivated reports whether all deferred tool categories have been activated.

func (*RequestToolsTool) FilterActiveTools added in v0.373.915512555 

func (r *RequestToolsTool) FilterActiveTools(tools []*llm.Tool) []*llm.Tool

FilterActiveTools returns non-deferred tools plus activated deferred tools. It excludes request_tools itself when all categories are activated.

func (*RequestToolsTool) HasDeferredTools added in v0.373.915512555 

func (r *RequestToolsTool) HasDeferredTools() bool

HasDeferredTools reports whether there are any deferred tools to manage.

func (*RequestToolsTool) IsCategoryActive added in v0.373.915512555 

func (r *RequestToolsTool) IsCategoryActive(category string) bool

IsCategoryActive reports whether a category has been activated.

func (*RequestToolsTool) Run added in v0.373.915512555 

func (r *RequestToolsTool) Run(_ context.Context, input json.RawMessage) llm.ToolOut

Run activates a deferred tool category.

func (*RequestToolsTool) Tool added in v0.373.915512555 

func (r *RequestToolsTool) Tool() *llm.Tool

Tool returns the llm.Tool for request_tools with a dynamically generated description.

type ScriptedToolsTool added in v0.389.953115655 

type ScriptedToolsTool struct {
	Tools      []*llm.Tool
	WorkingDir *MutableWorkingDir
	Timeout    time.Duration
}

ScriptedToolsTool runs Python scripts that can call other tools via IPC.

func (*ScriptedToolsTool) Run added in v0.389.953115655 

func (s *ScriptedToolsTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

Run executes a Python script with IPC-based tool calling.

func (*ScriptedToolsTool) Tool added in v0.389.953115655 

func (s *ScriptedToolsTool) Tool() *llm.Tool

Tool returns the llm.Tool for scripted_tools.

type ShellDisplayData added in v0.448.972577335 

type ShellDisplayData struct {
	WorkingDir string `json:"workingDir"`
	PID        int    `json:"pid,omitempty"`
	LogPath    string `json:"logPath,omitempty"`
	Yielded    bool   `json:"yielded,omitempty"`
}

ShellDisplayData is the display data sent to the UI for shell tool results.

type ShellTool added in v0.448.972577335 

type ShellTool struct {
	// CheckPermission is called before running any command, if set.
	CheckPermission PermissionCallback
	// EnableJITInstall enables just-in-time tool installation for missing commands.
	EnableJITInstall bool
	// WorkingDir is the shared mutable working directory.
	WorkingDir *MutableWorkingDir
	// LLMProvider provides access to LLM services for tool validation.
	LLMProvider LLMServiceProvider
	// ConversationID is the ID of the conversation this tool belongs to.
	// It is exposed to invoked commands via PERCY_CONVERSATION_ID.
	ConversationID string
	// BackgroundCtx is the long-lived context that owns spawned processes.
	// When nil, defaults to context.Background(): yielded jobs survive the
	// per-call ctx ending. Set this to a server- or conversation-lifetime
	// context to have percy reap background jobs on shutdown.
	BackgroundCtx context.Context
	// DefaultYield is the default yield_time_seconds (default 30s).
	DefaultYield time.Duration
	// MaxYield is the upper cap on yield_time_seconds (default 10m).
	MaxYield time.Duration
	// TempDir overrides the directory used for log files (default os.TempDir).
	TempDir string
}

ShellTool is a successor to BashTool that does not unconditionally kill commands on timeout. Instead, if the command does not finish within yield_time_seconds, the tool returns to the LLM with the tail of output, the PID of the still-running process, and the path to a temp log file the agent can use (via the bash tool) to poll, wait, or kill.

This lets the agent supervise long-running but bounded jobs (builds, tests, big rsync) without committing the whole tool call to a hard timeout.

func (*ShellTool) Run added in v0.448.972577335 

func (s *ShellTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

func (*ShellTool) Tool added in v0.448.972577335 

func (s *ShellTool) Tool() *llm.Tool

Tool returns an llm.Tool based on s.

type SkillLoadTool 

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

SkillLoadTool loads the full content of a skill's SKILL.md file by name.

func (*SkillLoadTool) Run 

func (s *SkillLoadTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

Run executes the skill_load tool.

func (*SkillLoadTool) Tool 

func (s *SkillLoadTool) Tool() *llm.Tool

Tool returns an llm.Tool for loading skill content.

type SubagentDB 

type SubagentDB interface {
	// GetOrCreateSubagentConversation retrieves or creates a subagent conversation.
	// Returns the conversation ID and the actual slug used (may differ from requested
	// slug if a numeric suffix was added for uniqueness).
	GetOrCreateSubagentConversation(ctx context.Context, slug, parentID, cwd string) (conversationID, actualSlug string, err error)
}

SubagentDB is the database interface for subagent operations. This is implemented by the db package.

type SubagentDisplayData 

type SubagentDisplayData struct {
	Slug           string `json:"slug"`
	ConversationID string `json:"conversation_id"`
}

SubagentDisplayData is the display data sent to the UI for subagent tool results.

type SubagentRunner 

type SubagentRunner interface {
	// RunSubagent runs a subagent conversation and returns the last response.
	// If wait is false, it starts processing in background and returns immediately.
	// timeout is the maximum time to wait for a response.
	RunSubagent(ctx context.Context, conversationID, prompt string, wait bool, timeout time.Duration, model string) (string, error)
}

SubagentRunner is the interface for running a subagent conversation. This is implemented by the server package to avoid import cycles.

type SubagentTool 

type SubagentTool struct {
	DB                   SubagentDB
	ParentConversationID string
	WorkingDir           *MutableWorkingDir
	Runner               SubagentRunner
}

SubagentTool provides the ability to spawn and interact with subagent conversations.

func (*SubagentTool) Run 

func (s *SubagentTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

func (*SubagentTool) Tool 

func (s *SubagentTool) Tool() *llm.Tool

Tool returns an llm.Tool for the subagent functionality.

type Timeouts 

type Timeouts struct {
	Fast time.Duration // regular commands (e.g., ls, echo, simple scripts)
	Slow time.Duration // commands that may reasonably take longer (e.g., downloads, builds, tests)
}

Timeouts holds the configurable timeout values for bash commands.

type TodoWriteTool 

type TodoWriteTool struct {
	WorkingDir           *MutableWorkingDir
	DB                   SubagentDB
	ParentConversationID string
	Runner               SubagentRunner
	VerifierModel        string
	VerifierEnabled      bool
}

TodoWriteTool manages a TODO.md checklist in the working directory.

func (*TodoWriteTool) Run 

func (t *TodoWriteTool) Run(ctx context.Context, m json.RawMessage) llm.ToolOut

Run executes the todo_write tool.

func (*TodoWriteTool) Tool 

func (t *TodoWriteTool) Tool() *llm.Tool

Tool returns an llm.Tool for managing TODO.md.

type ToolSet 

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

ToolSet holds a set of tools for a single conversation. Each conversation should have its own ToolSet.

func NewToolSet 

func NewToolSet(ctx context.Context, cfg ToolSetConfig) *ToolSet

func (*ToolSet) ActiveTools added in v0.373.915512555 

func (ts *ToolSet) ActiveTools() []*llm.Tool

ActiveTools returns only the currently active tools. Deferred tools are excluded unless their category has been activated via request_tools.

func (*ToolSet) AllTools added in v0.373.915512555 

func (ts *ToolSet) AllTools() []*llm.Tool

AllTools returns all tools including deferred ones.

func (*ToolSet) Cleanup 

func (ts *ToolSet) Cleanup()

Cleanup releases resources held by the tools (e.g., browser).

func (*ToolSet) WorkingDir 

func (ts *ToolSet) WorkingDir() *MutableWorkingDir

WorkingDir returns the shared working directory.

type ToolSetConfig 

type ToolSetConfig struct {
	// WorkingDir is the initial working directory for tools.
	WorkingDir string
	// LLMProvider provides access to LLM services for tool validation.
	LLMProvider LLMServiceProvider
	// EnableJITInstall enables just-in-time tool installation.
	EnableJITInstall bool
	// EnableBrowser enables browser tools.
	EnableBrowser bool
	// EnableCodeIntelligence enables LSP-based code intelligence tools.
	EnableCodeIntelligence bool
	// ModelID is the model being used for this conversation.
	// Used to determine tool configuration (e.g., simplified patch schema for weaker models).
	ModelID string
	// OnWorkingDirChange is called when the working directory changes.
	// This can be used to persist the change to a database.
	OnWorkingDirChange func(newDir string)
	// SubagentRunner is the runner for subagent conversations.
	// If set, the subagent tool will be available.
	SubagentRunner SubagentRunner
	// SubagentDB is the database for subagent conversations.
	SubagentDB SubagentDB
	// OrchestrateRunner runs the planner->builders->verifier pipeline.
	// If set, the orchestrate tool is available to top-level conversations.
	OrchestrateRunner OrchestrateRunner
	// ParentConversationID is the ID of the parent conversation (for subagent tool).
	ParentConversationID string
	// ConversationID is the ID of the conversation these tools belong to.
	// This is exposed to bash commands via the PERCY_CONVERSATION_ID environment variable.
	ConversationID string
	// SubagentDepth is the nesting depth of this conversation.
	// 0 = top-level conversation, 1 = subagent, 2 = sub-subagent, etc.
	SubagentDepth int
	// MaxSubagentDepth is the maximum nesting depth for subagents.
	// Subagent tool is only available when SubagentDepth < MaxSubagentDepth.
	// A value of 0 means no limit (but SubagentRunner/SubagentDB must still be set).
	// Set to 1 to allow only top-level conversations (depth 0) to spawn subagents.
	MaxSubagentDepth int
	// TodoVerifierModel is the model selector used to verify todo completion.
	// Empty disables todo verification.
	TodoVerifierModel string
	// MemorySearchTool is the pre-built memory search tool. If set, it's added to the tool set.
	MemorySearchTool *llm.Tool
	// AvailableSkills is the list of discovered skills. If non-empty, the skill_load tool is registered.
	AvailableSkills []skills.Skill
}

ToolSetConfig contains configuration for creating a ToolSet.

Source Files

View all Source files

Directories

Path Synopsis
Package browse provides browser automation tools for the agent
 Package browse provides browser automation tools for the agent
Package edit implements buffered position-based editing of byte slices.
 Package edit implements buffered position-based editing of byte slices.
Package onstart provides codebase analysis used to inform the initial system prompt.
 Package onstart provides codebase analysis used to inform the initial system prompt.

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.