Usage

Usage#

This guide covers common usage patterns and examples for gptme.

To start a new chat or select an existing one, run:

gptme

This will show you a list of past chats, allowing you to select one or start a new one.

To get inspiration for your first prompt, see the Examples.

Attaching Files and URLs#

Prefix a local file or directory with @ to include it in your prompt. Ordinary mentions such as README.md or src/ stay as text; the assistant can read them through tools when needed. In the default context mode, directories attach a bounded file listing, not every file’s contents.

gptme 'review this' @src/main.py @README.md
gptme 'what do you see?' @image.png
gptme 'summarize this' '`@my notes.txt`'

Inside a chat, use the same backtick-wrapped reference for names with spaces: `@my notes.txt`. Shell single quotes in the example preserve the backticks literally. Clipboard image paste in the CLI inserts an explicit attachment. Ordinary pasted text follows the same rules as typed text.

The CLI, TUI, queued prompts, and in-turn steering share this policy. GPTME_AUTO_INCLUDE_PATHS=1 restores legacy automatic inclusion of local path mentions. GPTME_DISABLE_PATH_INCLUDE=1 takes precedence and disables all text-discovered local paths and URLs, including explicit @ references. Files already attached through message metadata and configured prompt files remain independent of these flags.

HTTP/HTTPS URLs keep their existing behavior. In the default context mode, interactive CLI and TUI sessions ask which URLs to fetch; non-interactive sessions fetch them automatically. Declining a URL keeps the prompt text and skips fetching it. Paths and URLs inside fenced code blocks or XML blocks are excluded from discovery.

Inspect expansion without sending a model request with:

gptme-util prompts expand 'review @README.md'
GPTME_AUTO_INCLUDE_PATHS=1 gptme-util prompts expand 'review README.md'

This inspection command ignores GPTME_DISABLE_PATH_INCLUDE, as before, but respects the explicit-attachment default and GPTME_AUTO_INCLUDE_PATHS. It can read files and fetch URLs during expansion.

Commands#

gptme provides slash-commands for various actions within the chat. For the complete reference, see Commands.

Common commands:

  • /help - Show available commands

  • /undo [n] - Undo the last n actions

  • /log - Show the conversation log

  • /edit - Edit the conversation in your editor

  • /model - Show or switch the current model

  • /models - List available models

  • /tokens - Show token usage and costs

  • /exit - Exit the program

Managing Conversations#

Every gptme interaction is part of a conversation — a named history of messages persisted on disk. Conversations can be resumed, searched, forked, and renamed.

For term definitions (conversation, branch, fork, analytics session), see the Glossary.

Start or resume a named conversation

Give a conversation an explicit name so you can return to it later:

# Start a new named conversation
gptme --name my-refactor "let's refactor the auth module"

# Resume that same conversation in a future session
gptme --name my-refactor

# Resume the most recently modified conversation in the current workspace
gptme -r

--resume (or -r) is a flag, not an option taking a conversation ID. Use gptme --resume --name my-refactor to select a specific existing conversation and fail if it does not exist. Positional arguments are new prompts: gptme --resume "continue" sends a follow-up to the latest conversation. An apparent positional conversation ID is rejected with guidance instead of silently sending it to a different conversation; use gptme --resume -- my-refactor if you really intend the ID as prompt text.

Separate invocations in the same terminal can create separate conversations. Check the startup Using logdir line when choosing which history to resume.

Without --name, gptme assigns a random name (e.g. hopping-blue-robot).

List and search conversations

# List the 20 most recent conversations
gptme chats list

# Show full metadata (model, cost, token counts)
gptme chats list --metadata

# Search conversation content
gptme chats search "auth module refactor"

# Machine-readable JSON output
gptme chats list --json

Fork a conversation to explore an alternate approach

Forking creates a new independent conversation from messages up to turn N. The original conversation is unchanged.

# Fork after the third user+assistant exchange
gptme-util chats fork my-refactor --at-turn 3

# Fork with a custom name for the new conversation
gptme-util chats fork my-refactor --at-turn 3 --name my-refactor-v2

# Then resume the fork normally
gptme --name my-refactor-v2

Within a running conversation, /fork my-experiment achieves the same result at the current turn (see Commands).

Note

/fork and gptme-util chats fork both create a new top-level conversation, not a branch inside the current one. For workspace rollback before risky changes, use /checkpoint (committed state) or /snapshot (any state) instead.

Interfaces#

Besides the CLI, gptme can be used through:

  • Web - A web-based interface

  • App - Desktop and Android app (macOS, Windows, Linux, Android)

  • Cloud - Hosted gptme at gptme.ai

  • Channels - GitHub, email, chat apps, and voice

For more detailed information about specific features, check out:

  • Tools - Available tools and their usage

  • Providers - Supported LLM providers

  • Server - Running the web UI and REST API server

Features#

Here is a very quick overview of the main features of gptme.

Tools

gptme comes with a variety of tools for different tasks:

  • Shell - Execute shell commands

  • Python - Run Python code

  • Browser - Browse and interact with web content

  • Vision - Process and analyze images

See the Tools page for a complete list of available tools.

Writing Files#

You can ask the assistant to create new files or modify existing ones:

User 
implement game of life in life.py
Assistant 
Certainly! I'll create a new file named `life.py` implementing Conway's Game of Life. This implementation will use NumPy for efficient array operations and Matplotlib for visualization. Here's the code:
save life.py


import numpy as np
import matplotlib.pyplot as plt
from matplotlib.animation import FuncAnimation
...
System 
Saved to life.py

Making Changes#

You can start chats and request changes directly from the command line. The contents of any mentioned text files will be included as context, and the assistant will generate patches to apply the requested changes:

gptme 'make improvements to life.py so dead cells fade out over time'
User 
make improvements to life.py so dead cells fade out over time
life.py


...
Assistant 
To make alive cells green and dead cells black in the Game of Life simulation, we need to modify the colormap and how we represent the cell states. Here's the updated `life.py` script with these changes:
patch life.py


...
System 
Patch applied

Browser Integration#

With the Browser extras installed, the assistant can read URLs (included in the prompt or with its read_url tool) and “see” web pages by taking screenshots and viewing them.

Multiprompt syntax#

The - separator allows you to chain multiple prompts together, letting the assistant finish running tools for one prompt before moving on to the next:

gptme 'create a project' - 'add tests' - 'commit changes'

This is particularly useful for breaking down complex tasks into steps and creating Automation workflows.

Queue follow-up prompts#

If another gptme process is already busy in a conversation, queue the next user turn from a second terminal instead of waiting for the current step to finish:

gptme-util chats send chat-123 "once the tests finish, summarize the failures"

The running conversation will drain the queued prompt on its next turn. Use gptme-util chats list if you need to look up the conversation ID first.

Tool Selection Patterns#

Use --tools to control which tools are available.

  • --tools read,append replaces defaults with exactly those tools.

  • --tools +computer adds the computer tool on top of defaults.

# Add computer use while keeping the standard default tools
gptme --tools +computer "take a screenshot and summarize what you see"

For long visual tasks, use a subagent profile to avoid bloating parent context with repeated screenshots:

# Desktop interaction (mouse, keyboard, screenshots)
subagent(
    "computer-use",
    "Click the Submit button, wait for the modal, and screenshot the result",
)

# Web browsing and testing
subagent(
    "browser-use",
    "Navigate web app UI, capture evidence, and return a concise bug report",
)

See available profiles with:

gptme-util profile list

Minimal context mode#

When you want a tighter startup prompt for a specialized task, combine a short system prompt, a narrow tool set, and selective context:

gptme --system short --tools shell,read,patch,save --context files "fix the failing test"

Use --no-workspace to skip all project-specific context (prompt files and context_cmd output) in one flag — tools and the core prompt are still included:

gptme --no-workspace --system short --tools shell,read,patch,save "apply this patch"

Measure the prompt before and after with:

gptme --show-prompt-stats

That prints per-section token counts for the startup system prompt so you can see whether the cost is coming from tool docs, user profile text, workspace prompt files, or dynamic context_cmd output.

For a deeper recipe, see Run gptme with minimal context.

Skip confirmation prompts#

You can skip confirmation prompts using the --no-confirm flag. This is useful when you are confident the LLM will do what you want, so you don’t want to have to confirm actions:

gptme --no-confirm 'create a snake game using curses in snake.py, dont run it'

See Security for the trade-offs, and how to contain the risk when running without confirmations.

Non-interactive mode#

The --non-interactive flag runs gptme in a mode that terminates after completing all prompts. This is useful for scripting and automation:

gptme --non-interactive 'create a snake game using curses in snake.py, dont run it' '-' 'make the snake green and the apple red'

Note: --non-interactive implies --no-confirm, so you don’t need to specify both.

Machine-readable output#

Pair --non-interactive with --output-format json when stdout needs to be consumed by another program. In JSON mode, gptme emits one JSON object per line on stdout (JSONL):

gptme --non-interactive --output-format json 'summarize this repository'

Use --resume to continue an existing automated conversation without supplying a new prompt. This also picks up any queued follow-up prompts for the current conversation before exiting:

gptme --non-interactive --output-format json --resume

Pre-commit Integration#

gptme integrates with pre-commit to catch code quality issues early. When enabled, it will automatically run pre-commit checks after file modifications, right before yielding control back to the user, to let the assistant address issues without human intervention.

  • Enabled automatically if a .pre-commit-config.yaml exists in any parent directory

  • Can be explicitly enabled/disabled with GPTME_CHECK=true/false

  • Runs after file modifications to catch issues early

  • Shows output in conversation when issues are found

  • Distinguishes between automatically fixed issues and those requiring manual fixes

Example workflow:

User 
create a new file named main.py with a simple function
Assistant 
Sure! I'll create a new file named `main.py` with a simple function that adds two numbers together. Here's the code:
save main.py


def my_function(x, y):
    return x + y
System 
Saved to main.py
Assistant 
I have created the file.
System 
Pre-commit checks failed
stdout


typecheck................................................................Failed
- hook id: typecheck
- exit code: 1
main.py: error: Function is missing type hints
Assistant 
Typechecks failed, I'll update the function to use type hints.
patch main.py


<<<<<<< ORIGINAL
def my_function(x, y):
=======
def my_function(x: int, y: int) -> int:
>>>>>>> UPDATED
System 
Patch applied
Assistant 
Great, the typecheck should now pass.

For further usage examples, see the Examples page.

Terminal agent status#

The classic CLI and Textual TUI (fullscreen and inline) report lifecycle state using OSC 7501 (Program Status Protocol), as supported by herdr-core. A supporting terminal consumer can distinguish working, completed, and waiting-for-permission or waiting-for-answer states without scraping output. The working state spans the whole turn, including tool execution. Normal chat input after a completed turn keeps the completed state; startup reports idle, as does a turn that was interrupted or whose tool execution was declined. Reports are cleared when the chat exits.

Reports contain only the state, agent name, and blocking kind, not prompts or tool arguments. They are disabled for redirected output, JSON output, and quiet mode. Set GPTME_PROGRAM_STATUS=0 to disable them explicitly. The TUI sends reports through its terminal driver, including tool and URL approval dialogs, background commands, errors, and interruptions. Server UI reporting is not included. Background CLI threads and inline subagent sessions cannot overwrite the parent terminal status (an inline subagent’s permission and question prompts are still reported).

Standard tmux does not interpret OSC 7501. It needs an output consumer (for example, one connected with pipe-pane) to update pane options and status-line formats. Enabling allow-passthrough alone does not add tmux agent badges. OSC reports are untrusted terminal metadata, not an authentication or authorization mechanism.