Tools

Tools#

gptme’s tools enable AI agents to execute code, edit files, browse the web, process images, and interact with your computer.

Overview#

Each tool has its own reference page, listed here by category.

📁 File System#

  • Read - Read files in any format

  • Save - Create and overwrite files

  • Patch - Apply precise changes to existing files

  • Morph - Apply fast targeted edits using Morph Fast Apply

  • Hashline Edit - Snapshot-anchored line-range edits with stale-file detection

💻 Code & Development#

  • Python - Execute Python code interactively with full library access

  • Shell - Run shell commands and manage system processes

  • GH - Interact with GitHub issues, PRs, and repositories

  • Precommit - Automatically run pre-commit checks after file saves

  • Autocommit - Automatically prompt for git commits after file modifications

🌐 Web & Research#

  • Browser - Browse websites, take screenshots, and read web content

  • RAG - Index and search through documentation and codebases

  • Chats - Search past conversations for context and references

👁️ Visual & Interactive#

  • Vision - Analyze images, diagrams, and visual content

  • Screenshot - Capture your screen for visual context

  • Computer - Control desktop applications through visual interface

🤝 User Interaction#

  • Choice - Present multiple-choice options to the user

  • Elicit - Request structured single-field input from the user

  • Form - Present a multi-field form for structured user input

⚡ Advanced Workflows#

  • Tmux - Manage long-running processes in terminal sessions

  • Subagent - Delegate subtasks to specialized agent instances

  • Complete - Signal that the autonomous session is finished

  • Restart - Restart the gptme process after configuration changes

  • Vent - Emit in-the-moment friction signals to a durable ledger

  • Request tool change - Record a structured request for a different tool configuration (opt-in, audit-only)

🧠 Knowledge & Planning#

  • Lessons - Access contextual lessons and behavioral guidance

  • Todo - Manage a conversation-scoped working memory task list

🔌 Extensions#

  • MCP - Discover and connect Model Context Protocol servers

Tool Interface Architecture#

gptme’s default tool interface is Programmatic Tool Calling (PTC): the model writes executable code in fenced code blocks, and gptme runs it directly. For the default markdown and xml formats, no JSON schemas are sent to the model and no JSON-structured responses are parsed.

The primary dispatch path is "markdown" format: a fenced code block whose language tag identifies any registered tool name (python, shell, save, patch, and others), and whose content gptme routes to ToolSpec.execute(code, args, kwargs). For Python, this means IPython’s run_cell(); for Shell, subprocess.Popen with a stateful bash shell.

gptme also supports a provider-native tool mode ("tool" format) for OpenAI and Anthropic APIs, where ToolSpec parameters are converted to JSON-schema definitions and sent to the provider — trading context-rot resilience for provider-side tool routing compatibility.

Why default to PTC? A 2026 benchmark study (arXiv:2608.06370, “The Bitter Lesson of Tool Calling”) found that PTC matches or exceeds JSON-schema tool calling on 11/14 models and — critically — maintains accuracy under context rot (long sessions with accumulated tool history) while JSON-schema accuracy degrades ~2.3%. Autonomous gptme sessions routinely accumulate 50–200 tool calls; this is exactly the regime where JSON-schema approaches falter.

See Design: Programmatic Tool Calling (PTC) Interface for the full architecture documentation and 2026-08-13 audit of dispatch paths in gptme/tools/.

Combinations#

The real power emerges when tools work together:

  • Web Research + Code: Browser + Python - Browse documentation and implement solutions

  • Visual Development: Vision + Patch - Analyze UI mockups and update code accordingly

  • System Automation: Shell + Python - Combine system commands with data processing

  • Interactive Debugging: Screenshot + Computer - Visual debugging and interface automation

  • Knowledge-Driven Development: RAG + Chats - Learn from documentation and past conversations

Tool Selection & Allowlists#

By default gptme loads its full built-in toolset. You can restrict which tools are active for a given run — either to reduce the agent’s surface area or to build read-only / sandboxed profiles.

Basic usage#

Pass a comma-separated list of tool names to --tools (CLI) or set the TOOL_ALLOWLIST environment variable:

# Exact names — only these tools are loaded
gptme --tools save,patch,shell,python "refactor this file"

# Additive: start from defaults and add more
gptme --tools +rag,browser "research this topic"

# Subtractive: start from defaults and remove specific tools
gptme --tools -shell,computer "safer mode"

# Disable all tools (pure conversation)
gptme --tools "" "just talk to me"

# Strict audit mode: only the built-in read tool, no writes or execution
gptme --tools read-only "summarise this repo"

Glob patterns (*, ?, [...]) are also supported, matched against tool names with fnmatch.fnmatchcase().

read-only is a named preset, not a hint pattern. It expands to the built-in read tool only, and cannot be combined with other tool names. This makes it safe for auditing untrusted workspaces where shell, ipython, save, append and patch must stay unavailable. Use hint:read-only only when you explicitly want to trust third-party tool annotations, such as MCP server metadata.

Hint-based patterns#

Tools can carry capability hints — semantic tags that describe what a tool does. Hint-based allowlist entries let you match entire categories of tools at once using the hint: prefix:

# Allow only tools annotated as read-only
gptme --tools "hint:read-only" "summarise this repo"

# Mix exact names with hint patterns
gptme --tools "shell,patch,hint:read-only" "analyse and fix"

The following hints are defined:

Hint

Meaning

read-only

Tool only reads state; never writes, creates, or deletes.

destructive

Tool may modify or delete state. Use with caution in automated runs.

idempotent

Tool is safe to call multiple times with the same arguments.

closed-world

Tool affects only local state; it does not make network requests or reach outside the current environment.

Note

The built-in read tool carries the read-only hint. MCP tools can also carry the hint through server-supplied annotations (see below), so hint:read-only is broader than the strict read-only preset.

MCP tool annotations#

When gptme connects to an MCP server, each tool’s ToolAnnotations are mapped to gptme hints:

MCP annotation

Value

gptme hint

readOnlyHint

true

read-only

destructiveHint

true (and not read-only)

destructive

idempotentHint

true

idempotent

openWorldHint

false

closed-world

Example MCP server configuration that exposes a read-only filesystem tool:

{
  "name": "my-tools",
  "description": "My safe read-only tools",
  "tools": [
    {
      "name": "read_file",
      "description": "Read a file from disk",
      "annotations": {
        "readOnlyHint": true,
        "idempotentHint": true
      }
    }
  ]
}

Once connected, gptme --tools "hint:read-only" will include read_file while excluding any MCP tools without the read-only annotation.

Example profiles#

These are ad-hoc allowlists; for gptme’s built-in agent profiles (explorer, researcher, developer, verifier), see Agent Profiles.

Read-only research agent — cannot write files or run commands:

gptme --tools "browser,rag,chats,hint:read-only" "research X"

Minimal coding agent — file editing only, no shell or browser:

gptme --tools "read,save,patch,morph,python" "refactor this module"

Safe MCP integration — built-in defaults plus only read-only MCP tools:

gptme --tools "+hint:read-only" "help me explore this codebase"

Subagent with restricted tool set — useful in [agent] config or when spawning subagents programmatically:

# gptme.toml
[env]
TOOL_ALLOWLIST = "shell,patch,save,read,hint:read-only"

Tools that reference other tools#

Tool instructions and examples often describe how tools interact (“fetch the URL with read”, “use hashline_edit after read”). Such text is only true when the other tool is loaded, and a model that reads it will happily call a tool it does not have. Two mechanisms keep this coherent:

Conditional blocks in instructions, instructions_format and examples are rendered against the loaded toolset when the prompt is built:

Do **not** use vision for:
{% if tools: read, browser %}
- Images at a URL — fetch with `read` or visit with `browser` instead
{% elif tools: read %}
- Images at a URL — fetch with `read` first, then pass the local path
{% endif %}

A branch is taken when all the listed tools are loaded; {% elif %} and {% else %} behave as expected; blocks do not nest. A marker on its own line removes the whole line, so lists stay tidy. Generated documentation renders every branch as if all tools were loaded.

Companion tools are declared with requires_tools on the ToolSpec. Enabling hashline_edit loads read as well (its edits are anchored to read’s snapshot tags), even though read is disabled by default on its own. A startup allowlist must include every required companion; otherwise initialization fails rather than widening the configured capability boundary. An explicit /tools load user action may load the requested tool and its companions together:

tool = ToolSpec(
    name="hashline_edit",
    ...,
    disabled_by_default=True,
    requires_tools=["read"],
)
Contents