llmtools

README

LLM Tools for Go

Go-native and cross-platform "tool" implementations for common local tasks, plus a small registry that makes them easy to expose to LLM tool-calling systems.

Table of contents

• Features at a glance
  • File system tools
  • Execute tools
  • Text processing tools
  • Image tools
• Package overview
• Registry
• Tool outputs
• Sandboxing and path policy
• Examples
• Exec tool notes
• Development
• License

Features at a glance

• Sandboxed execution for all tools under a enforced allowed roots and work directory.
• Symlinks are rejected throughout for safety.
• All implementations are cross-platform supporting lin/win/mac systems.
• Normalized tool spec to support text/image/binary output formats.
• Fully modular code for any customizations needed.

File system tools

• Grouped under: fstool.

• readfile:

  • encoding=text: reads UTF-8 text only (rejects non-text), with PDF text extraction support when the file is a PDF.
  • encoding=binary: returns base64, emitting image outputs for image/* MIME types and file outputs otherwise.
  • Safety: size caps and symlink-traversal hardening.

• writefile:

  • encoding=text: write UTF-8 content
  • encoding=binary: write base64-decoded bytes
  • Options: overwrite, createParents (bounded), atomic writes, size caps, symlink hardening.

• deletefile:

  • “Safe delete” by moving to trash.
  • trashDir=auto tries system trash when possible; falls back to a local .trash directory.
  • Uses unique naming, best-effort cross-device handling, and avoids destructive removal when possible.

• searchfiles: Recursively search file paths and UTF-8 text content using RE2 regex.

• listdirectory: List entries under a directory, optionally filtered by glob.

• statpath: Inspect a path (exists, size, timestamps, directory flag).

• mimeforpath: Best-effort MIME type detection (extension + sniffing).

• mimeforextension: MIME lookup for an extension.

Execute tools

• Grouped under: exectool

• shellcommand:

  • Execute one or more commands via a selected shell (auto, sh, bash, pwsh, powershell, cmd, etc).
  • Enforces timeouts/output caps/command caps.
  • Supports session-like persistence for workdir and environment across calls (note: not a persistent shell process).

• runscript:

  • Run an existing script from disk with arguments and environment overrides.
  • Extension-based interpreter selection via RunScriptPolicy (host-configurable).

Text processing tools

• Grouped under: texttool

• readtextrange: Read lines, optionally constrained by unique start/end marker blocks.

• findtext: Find matches with context (modes: substring, regex (RE2/Go), exact line-block).

• inserttextlines: Insert lines at start/end or relative to a uniquely matched anchor block.

• replacetextlines: Replace exact line blocks; can disambiguate with immediate adjacent beforeLines/afterLines.

• deletetextlines: Delete exact line blocks; can disambiguate with immediate adjacent beforeLines/afterLines.

Image tools

• Grouped under: imagetool

• readimage: Read intrinsic metadata (width/height/format/MIME), optionally include base64 content.

Package overview

• llmtools: Registry + tool registration helpers.
• spec: Tool manifests + output union types.
• fstool: Filesystem tools.
• exectool: Shell command execution and script execution.
• texttool: Safe, deterministic line-based text editing tools.
• imagetool: Image tools.

Registry

The registry provides:

• tool registration + lookup by spec.FuncID
• stable manifest ordering (Tools() sorted by slug + funcID)
• per-registry default call timeout via WithDefaultCallTimeout
• per-call timeout override via llmtools.WithCallTimeout(...)
• panic-to-error recovery around tool execution

Tool outputs

• Registry.Call returns []spec.ToolOutputUnion.

• The call wrapper can modify the union to support two common patterns:

  • Structured JSON-as-text (most tools)

    • Most tools are registered via RegisterTypedAsTextTool, which wraps the tool’s Go output as JSON and returns it as a single text output item.

  • Typed content outputs

    • text output for UTF-8 text / extracted PDF text
    • image output for images when encoding=binary
    • file output for all other binaries when encoding=binary
    • E.g.: readfile: This output makes readfile suitable for LLM systems that support multi-modal/file outputs.

Sandboxing and path policy

All Tools are are instance-owned tools. Hosts can configure:

• workBaseDir: base directory for resolving relative paths
• allowedRoots: optional allowlist roots; when set, all resolved paths must stay within these roots

This is the recommended way to run the tools safely inside a sandbox (for example, inside a temp workspace or per-user directory).

Examples

All examples are provided as end-to-end integration tests that:

• start from a registry
• register tools (sandboxed to a temp directory)
• execute realistic sequences: read/modify loops, text edits, shell sessions, script execution, binary/image workflows

Examples:

• Text read/modify loop (find/replace/insert/delete + verification): text test
• Filesystem + MIME + safe delete (trash) + binary/image flows: fs + image test
• Shell sessions + environment persistence + runscript: exec test

Exec tool notes

• OS support

  • Cross-platform shell selection: auto chooses a safe default per OS.
  • Windows prefers pwsh, then Windows PowerShell, then cmd.

• Timeouts

  • The registry may enforce a call timeout (WithDefaultCallTimeout).
  • shellcommand and runscript also enforce execution policy timeouts.
  • Ensure the registry timeout is >= tool execution timeout (or set registry timeout to 0) to avoid premature cancellation.

• Safety knobs

  • ExecutionPolicy caps total commands, command length, output bytes, and timeout.
  • “Hard blocked” commands are always blocked.
  • Heuristic checks (fork-bomb/backgrounding patterns) can be toggled via AllowDangerous.

• RunScriptPolicy

  • Interpreter selection is extension-based and host-configurable.
  • Hosts can tighten allowed extensions and interpreter mappings.

Development

• Formatting follows gofumpt and golines via golangci-lint. Rules are in .golangci.yml.
• Useful scripts are defined in taskfile.yml; requires Task.
• Bug reports and PRs are welcome:
  • Keep the public API (package llmtools and spec) small and intentional.
  • Avoid leaking provider‑specific types through the public surface; put them under internal/.
  • Please run tests and linters before sending a PR.

License

Copyright (c) 2026 - Present - Pankaj Pipada

All source code in this repository, unless otherwise noted, is licensed under the MIT License. See LICENSE for details.

Documentation

Index

• func RegisterBuiltins(r *Registry) error
• func RegisterOutputsTool[T any](r *Registry, tool spec.Tool, ...) error
• func RegisterTypedAsTextTool[T, R any](r *Registry, tool spec.Tool, fn func(context.Context, T) (R, error)) error
• type CallOption
  • func WithCallTimeout(d time.Duration) CallOption
• type Registry
  • func NewBuiltinRegistry(opts ...RegistryOption) (*Registry, error)
  • func NewRegistry(opts ...RegistryOption) (*Registry, error)
  • func (r *Registry) Call(ctx context.Context, funcID spec.FuncID, in json.RawMessage, ...) ([]spec.ToolOutputUnion, error)
  • func (r *Registry) Lookup(funcID spec.FuncID) (spec.ToolFunc, bool)
  • func (r *Registry) RegisterTool(tool spec.Tool, fn spec.ToolFunc) error
  • func (r *Registry) Tools() []spec.Tool
• type RegistryOption
  • func WithDefaultCallTimeout(d time.Duration) RegistryOption
  • func WithLogger(logger *slog.Logger) RegistryOption

Functions

func RegisterBuiltins

func RegisterBuiltins(r *Registry) error

RegisterBuiltins registers the built-in tools into r.

func RegisterOutputsTool

func RegisterOutputsTool[T any](
	r *Registry,
	tool spec.Tool,
	fn func(context.Context, T) ([]spec.ToolOutputUnion, error),
) error

RegisterOutputsTool registers a typed tool function that directly returns []ToolOutputUnion. This is a function and not a method on struct as methods cannot have type params in go.

func RegisterTypedAsTextTool

func RegisterTypedAsTextTool[T, R any](
	r *Registry,
	tool spec.Tool,
	fn func(context.Context, T) (R, error),
) error

RegisterTypedAsTextTool registers a typed tool function whose output R is JSON-encodable. The JSON representation of R is wrapped into a single text block. This is a function and not a method on struct as methods cannot have type params in go.

Types

type CallOption

type CallOption func(*callOptions)

CallOption configures per-call behavior.

func WithCallTimeout

func WithCallTimeout(d time.Duration) CallOption

WithCallTimeout overrides the timeout for this single call. 0 means "no timeout" for this call (even if tool/registry default is non-zero).

type Registry

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

Registry provides lookup/register for Go tools by funcID, with json.RawMessage I/O.

func NewBuiltinRegistry

func NewBuiltinRegistry(opts ...RegistryOption) (*Registry, error)

NewBuiltinRegistry returns a Registry with all built-in tools registered. By default it applies a 10mins timeout, but callers can override it by passing WithDefaultCallTimeout as a later option.

func NewRegistry

func NewRegistry(opts ...RegistryOption) (*Registry, error)

func (*Registry) Call

func (r *Registry) Call(
	ctx context.Context,
	funcID spec.FuncID,
	in json.RawMessage,
	callOpts ...CallOption,
) ([]spec.ToolOutputUnion, error)

func (*Registry) Lookup

func (r *Registry) Lookup(funcID spec.FuncID) (spec.ToolFunc, bool)

func (*Registry) RegisterTool

func (r *Registry) RegisterTool(tool spec.Tool, fn spec.ToolFunc) error

func (*Registry) Tools

func (r *Registry) Tools() []spec.Tool

type RegistryOption

type RegistryOption func(*Registry) error

func WithDefaultCallTimeout

func WithDefaultCallTimeout(d time.Duration) RegistryOption

func WithLogger

func WithLogger(logger *slog.Logger) RegistryOption