Gptme

What is Gptme about?

Gptme is a terminal‑based AI assistant that augments large language models with practical tools such as a shell executor, file patcher, web browser, and vision capabilities. It enables developers and knowledge workers to interact with LLMs as if they had direct access to the local computer environment.

How to use Gptme?

1. Installation – install with pipx install gptme (requires Python 3.10+).
2. Start a session – run gptme or pass a prompt: gptme "write a Python script that fetches Bitcoin price".
3. Interact – type natural‑language commands; use slash commands (/undo, /tools, /model, etc.) to control the session.
4. Advanced usage – specify a model (-m openai/gpt-4), workspace (-w path), enable/disable specific tools (-t shell,patch,browser), or run in non‑interactive mode for scripting.

Key features of Gptme

• Code execution – run shell commands and Python code via built‑in tools.
• File manipulation – read, write, and apply incremental patches to files.
• Web browsing – search and scrape sites using a Playwright‑based browser tool.
• Vision – analyze images from prompts, screenshots, or web pages.
• Self‑correction – loop output back into the model for iterative improvement.
• Multi‑provider support – OpenAI, Anthropic, OpenRouter, local llama.cpp models.
• Web UI & REST API – optional browser interface and programmable API.
• Computer‑use tool – full desktop interaction (mouse, keyboard, GUI apps).
• Agent architecture – persistent agents, sub‑agents, and custom tool extensions.
• Developer ergonomics – tab completion, syntax‑highlighted diffs, TTS, tool sounds, and configurable feature flags.

Use cases of Gptme

• Software development – generate, test, and debug code without leaving the terminal.
• Shell assistance – translate natural language queries into complex CLI commands.
• Data analysis – run notebooks, process CSV/JSON, and visualize results on‑the‑fly.
• Learning & experimentation – explore new libraries or APIs interactively.
• RAG & knowledge work – fetch information from the web or local docs and incorporate it into responses.
• Automation – script repetitive tasks by chaining tool calls within an agent session.

FAQ

Q: Do I need an internet connection? A: Only when using remote LLM providers or the web‑browser tool. Local models (llama.cpp) run entirely offline.

Q: How is privacy handled? A: When using local models, no data leaves the machine. Remote providers follow their own policies; you can restrict usage to local models for full privacy.

Q: Can I extend Gptme with new tools? A: Yes. Tools are modular Python classes; adding a new tool involves implementing the required interface and registering it.

Q: What platforms are supported? A: Works on macOS, Linux, and Windows (via WSL or native Python). The web UI is browser‑agnostic.

Q: How do I run Gptme as a server? A: Use the built‑in server command (gptme --serve) to start the REST API and optional web UI.

📚 Table of Contents

• 🎥 Demos
• 🌟 Features
• 🚀 Getting Started
• 🛠 Usage
• 📊 Stats
• 🔗 Links

🎥 Demos

[!NOTE] These demos are very out of date (2023) and do not reflect the latest capabilities.

You can find more Demos and Examples in the documentation.

🌟 Features

• 💻 Code execution
  • Executes code in your local environment with the shell and python tools.
• 🧩 Read, write, and change files
  • Makes incremental changes with the patch tool.
• 🌐 Search and browse the web.
  • Can use a browser via Playwright with the browser tool.
• 👀 Vision
  • Can see images referenced in prompts, screenshots of your desktop, and web pages.
• 🔄 Self-correcting
  • Output is fed back to the assistant, allowing it to respond and self-correct.
• 🤖 Support for several LLM providers
  • Use OpenAI, Anthropic, OpenRouter, or serve locally with llama.cpp
• 🌐 Web UI and REST API
  • Modern web interface at chat.gptme.org (gptme-webui)
  • Simple built-in web UI included in the Python package
  • Server with REST API
  • Standalone executable builds available with PyInstaller
• 💻 Computer use tool, as hyped by Anthropic (see #216)
  • Give the assistant access to a full desktop, allowing it to interact with GUI applications.
• 🤖 Long-running agents and advanced agent architectures (see #143 and #259)
  • Create your own agent with persistence using gptme-agent-template, like Bob.
• ✨ Many smaller features to ensure a great experience
  • 🚰 Pipe in context via stdin or as arguments.
    • Passing a filename as an argument will read the file and include it as context.
  • → Smart completion and highlighting:
    • Tab completion and highlighting for commands and paths
  • 📝 Automatic naming of conversations
  • ✅ Detects and integrates pre-commit
  • 🗣️ Text-to-Speech support, locally generated using Kokoro
  • 🔊 Tool sounds: Pleasant notification sounds for different tool operations
    • Enable with GPTME_TOOL_SOUNDS=true
    • Different sounds for shell commands, file operations, screenshots, etc.
  • 🎯 Feature flags for advanced usage, see configuration docs

🛠 Use Cases

• 🖥 Development: Write and run code faster with AI assistance.
• 🎯 Shell Expert: Get the right command using natural language (no more memorizing flags!).
• 📊 Data Analysis: Process and analyze data directly in your terminal.
• 🎓 Interactive Learning: Experiment with new technologies or codebases hands-on.
• 🤖 Agents & Tools: Experiment with agents & tools in a local environment.

🛠 Developer perks

• 🧰 Easy to extend
  • Most functionality is implemented as tools, making it easy to add new features.
• 🧪 Extensive testing, high coverage.
• 🧹 Clean codebase, checked and formatted with mypy, ruff, and pyupgrade.
• 🤖 GitHub Bot to request changes from comments! (see #16)
  • Operates in this repo! (see #18 for example)
  • Runs entirely in GitHub Actions.
• 📊 Evaluation suite for testing capabilities of different models
• 📝 gptme.vim for easy integration with vim

🚧 In progress

• 🌳 Tree-based conversation structure (see #17)
• 📜 RAG to automatically include context from local files (see #59)
• 🏆 Advanced evals for testing frontier capabilities

🚀 Getting Started

Install with pipx:

# requires Python 3.10+
pipx install gptme

Now, to get started, run:

gptme

Here are some examples:

gptme 'write an impressive and colorful particle effect using three.js to particles.html'
gptme 'render mandelbrot set to mandelbrot.png'
gptme 'suggest improvements to my vimrc'
gptme 'convert to h265 and adjust the volume' video.mp4
git diff | gptme 'complete the TODOs in this diff'
make test | gptme 'fix the failing tests'

For more, see the Getting Started guide and the Examples in the documentation.

🛠 Usage

$ gptme --help
Usage: gptme [OPTIONS] [PROMPTS]...

  gptme is a chat-CLI for LLMs, empowering them with tools to run shell
  commands, execute code, read and manipulate files, and more.

  If PROMPTS are provided, a new conversation will be started with it. PROMPTS
  can be chained with the '-' separator.

  The interface provides user commands that can be used to interact with the
  system.

  Available commands:
    /undo         Undo the last action
    /log          Show the conversation log
    /tools        Show available tools
    /model        List or switch models
    /edit         Edit the conversation in your editor
    /rename       Rename the conversation
    /fork         Copy the conversation using a new name
    /summarize    Summarize the conversation
    /replay       Rerun tools in the conversation, won't store output
    /impersonate  Impersonate the assistant
    /tokens       Show the number of tokens used
    /export       Export conversation as HTML
    /commit       Ask assistant to git commit
    /setup        Setup gptme with completions and configuration
    /help         Show this help message
    /exit         Exit the program

  Keyboard shortcuts:
    Ctrl+X Ctrl+E  Edit prompt in your editor
    Ctrl+J         Insert a new line without executing the prompt

Options:
  --name TEXT            Name of conversation. Defaults to generating a random
                         name.
  -m, --model TEXT       Model to use, e.g. openai/gpt-5, anthropic/claude-
                         sonnet-4-20250514. If only provider given then a
                         default is used.
  -w, --workspace TEXT   Path to workspace directory. Pass '@log' to create a
                         workspace in the log directory.
  --agent-path TEXT      Path to agent workspace directory.
  -r, --resume           Load most recent conversation.
  -y, --no-confirm       Skip all confirmation prompts.
  -n, --non-interactive  Non-interactive mode. Implies --no-confirm.
  --system TEXT          System prompt. Options: 'full', 'short', or something
                         custom.
  -t, --tools TEXT       Tools to allow as comma-separated list. Available:
                         append, browser, chats, choice, computer, gh,
                         ipython, morph, patch, rag, read, save, screenshot,
                         shell, subagent, tmux, tts, vision, youtube.
  --tool-format TEXT     Tool format to use. Options: markdown, xml, tool
  --no-stream            Don't stream responses
  --show-hidden          Show hidden system messages.
  -v, --verbose          Show verbose output.
  --version              Show version and configuration information
  --help                 Show this message and exit.

📊 Stats

⭐ Stargazers over time

📈 Download Stats

• PePy
• PyPiStats

🔗 Links

• Website
• Documentation
• GitHub
• Discord