Tools#

Tools available in gptme.

The main tools can be grouped in the following categories:

execution
- Shell
- Python
- Tmux
filesystem
- Save
- Patch
network
- Browser
chat management
- Chats

Shell#

The assistant can execute shell commands by outputting code blocks with bash or sh as the language.

# Examples

User	list the current directory
Assistant	To list the files in the current directory, use `ls`: bash ls
System	Ran command: `ls` stdout file1.txt file2.txt

The assistant can learn context by exploring the filesystem

User	learn about the project
Assistant	Lets start by checking the files bash git ls-files
System	output README.md main.py
Assistant	Now lets check the README bash cat README.md
System	stdout (contents of README.md)
Assistant	Now we check main.py bash cat main.py
System	output (contents of main.py)
Assistant	The project is...

Create vue project

User

Create a new vue project with typescript and pinia named fancy-project

Assistant

Sure! Let's create a new vue project with TypeScript and Pinia named fancy-project:bash
npm init vue@latest fancy-project --yes -- --typescript --pinia

System

output
> npx
> create-vue

Vue.js - The Progressive JavaScript Framework

Scaffolding project in ./fancy-project...

gptme.tools.shell.execute_shell(code: str, ask: bool, args: list[str]) → Generator[Message, None, None]: Executes a shell command and returns the output.

Python#

The assistant can execute Python code blocks.

It uses IPython to do so, and persists the IPython instance between calls to give a REPL-like experience.

# Examples

Results of the last expression will be displayed, IPython-style:

User	What is 2 + 2?
Assistant	ipython 2 + 2
System	Executed code block. result 4

It can write an example and then execute it:

User

compute fib 10

Assistant

To compute the 10th Fibonacci number, we write a recursive function:python
def fib(n):
    ...

Now, let's execute this code to get the 10th Fibonacci number:ipython
def fib(n):
    if n <= 1:
        return n
    return fib(n - 1) + fib(n - 2)
fib(10)

System

Executed code block.result
55

gptme.tools.python.execute_python(code: str, ask: bool, args=None) → Generator[Message, None, None]: Executes a python codeblock and returns the output.

gptme.tools.python.get_installed_python_libraries() → set[str]: Check if a select list of Python libraries are installed.

gptme.tools.python.register_function(func: T) → T: Decorator to register a function to be available in the IPython instance.

Tmux#

You can use the tmux tool to run long-lived and/or interactive applications in a tmux session. Requires tmux to be installed.

This tool is suitable to run long-running commands or interactive applications that require user input. Examples of such commands: npm run dev, python3 server.py, python3 train.py, etc. It allows for inspecting pane contents and sending input.

# Examples

Managing a dev server

User	Start the dev server
Assistant	Certainly! To start the dev server we should use tmux: tmux new_session 'npm run dev'
System	Running `npm run dev` in session 0

User

Can you show me the current content of the pane?

Assistant

Of course! Let's inspect the pane content:tmux
inspect_pane 0

System

output
Server is running on localhost:5600

User	Stop the dev server
Assistant	I'll send 'Ctrl+C' to the pane to stop the server: tmux send_keys 0 C-c
System	Sent 'C-c' to pane 0

Get info from ncurses applications

User	start top and give me a summary
System	Running `top` in session 1. output (output from top shown here)
Assistant	The load is...

gptme.tools.tmux.execute_tmux(code: str, ask: bool, args: list[str]) → Generator[Message, None, None]: Executes a command in tmux and returns the output.

Save#

Gives the assistant the ability to save/write code to a file.

# Examples

User	write a hello world script to hello.py save hello.py print("Hello world")
System	Saved to `hello.py`

User	make it all-caps save hello.py print("HELLO WORLD")
System	Saved to `hello.py`

# Examples

User	append a print "Hello world" to hello.py
Assistant	append hello.py print("Hello world")
System	Appended to `hello.py`

gptme.tools.save.execute_append(code: str, ask: bool, args: list[str]) → Generator[Message, None, None]: Append code to a file.

gptme.tools.save.execute_save(code: str, ask: bool, args: list[str]) → Generator[Message, None, None]: Save code to a file.

Patch#

Gives the LLM agent the ability to patch text files, by using a adapted version git conflict markers.

# Examples

User

patch the file `hello.py` to ask for the name of the user

Assistant

```patch hello.py
<<<<<<< ORIGINAL
def hello():
    print("Hello world")
=======
def hello():
    name = input("What is your name? ")
    print(f"Hello {name}")
>>>>>>> UPDATED
```

System

Patch applied

class gptme.tools.patch.Patch

Patch(original: str, updated: str)

__init__(original: str, updated: str) → None

diff_minimal(strip_context=False) → str: Show a minimal diff of the patch. Note that a minimal diff isn’t necessarily a unique diff.

gptme.tools.patch.apply(codeblock: str, content: str) → str: Applies multiple patches in codeblock to content.

gptme.tools.patch.execute_patch(code: str, ask: bool, args: list[str]) → Generator[Message, None, None]: Applies the patch.

Browser#

Tools to let the assistant control a browser, including:

loading pages
reading their contents
viewing them through screenshots
searching

Note

This is an experimental feature. It needs some work to be more robust and useful.

# Examples

Answer question from URL with browsing

User	find out which is the latest ActivityWatch version from superuserlabs.org
Assistant	Let's browse the site. ipython read_url("https://superuserlabs.org/")
System	https://superuserlabs.org/ ... [ActivityWatch](https://activitywatch.net/) ...
Assistant	Couldn't find the answer on the page. Following link to the ActivityWatch website. ipython read_url("https://activitywatch.net/")
System	https://activitywatch.net/ ... Download latest version v0.12.2 ...
Assistant	The latest version of ActivityWatch is v0.12.2

Searching

User	who is the founder of ActivityWatch?
Assistant	Let's search for that. ipython search("ActivityWatch founder")
System	results 1. [ActivityWatch](https://activitywatch.net/) ...
Assistant	Following link to the ActivityWatch website. ipython read_url("https://activitywatch.net/")
System	https://activitywatch.net/ ... The ActivityWatch project was founded by Erik Bjäreholt in 2016. ...
Assistant	The founder of ActivityWatch is Erik Bjäreholt.

Take screenshot of page

User

take a screenshot of the ActivityWatch website

Assistant

Certainly! I'll use the browser tool to screenshot the ActivityWatch website.ipython
screenshot_url("https://activitywatch.net")

System


Screenshot saved to screenshot.png

gptme.tools.browser.read_url(url: str) → str: Read the text of a webpage and return the text in Markdown format.

gptme.tools.browser.screenshot_url(url: str, filename: str | None = None) → str: Take a screenshot of a webpage and save it to a file.

gptme.tools.browser.search(query: str, engine: Literal['google', 'duckduckgo'] = 'google') → str: Search for a query on a search engine.

Chats#

List, search, and summarize past conversation logs.

# Examples

Search for a specific topic in past conversations

User

Can you find any mentions of "python" in our past conversations?

Assistant

Certainly! I'll search our past conversations for mentions of "python" using the search_chats function.ipython
search_chats("python")

gptme.tools.chats.list_chats(max_results: int = 5, include_summary: bool = False) → None

List recent chat conversations and optionally summarize them using an LLM.

Parameters:

max_results (int) – Maximum number of conversations to display.
include_summary (bool) – Whether to include a summary of each conversation. If True, uses an LLM to generate a comprehensive summary. If False, uses a simple strategy showing snippets of the first and last messages.

gptme.tools.chats.read_chat(conversation: str, max_results: int = 5, incl_system=False) → None

Read a specific conversation log.

Parameters:

conversation (str) – The name of the conversation to read.
max_results (int) – Maximum number of messages to display.
incl_system (bool) – Whether to include system messages.

gptme.tools.chats.search_chats(query: str, max_results: int = 5, system=False) → None

Search past conversation logs for the given query and print a summary of the results.

Parameters:

query (str) – The search query.
max_results (int) – Maximum number of conversations to display.
system (bool) – Whether to include system messages in the search.

Tools

Contents

Tools#

Shell#

Python#

Tmux#

Save#

Patch#

Browser#

Chats#