gptme - agent in your terminal

gptme

/ʤiː piː tiː miː/
what does it stand for?

Getting Started • GitHub • Documentation

Build Status Docs Build Status Codecov
PyPI version PyPI - Downloads all-time PyPI - Downloads per day
Discord X.com
Powered by gptme

📜 A personal AI agent in your terminal, with tools to:
run shell commands, write code, edit files, browse the web, use vision, and much more.
A great coding agent, but general-purpose enough to assist in all kinds of knowledge-work.

An unconstrained local free and open-source alternative to Claude Code, Codex, Cursor Agents, etc.
One of the first agent CLIs created (Spring 2023) — and still in very active development.

📚 Table of Contents

📢 News

For more history, see the Timeline and Changelog.

🎥 Demos

Note

The screencasts below are from 2023. gptme has evolved a lot since then! For up-to-date examples and screenshots, see the Documentation. We're working on automated demo generation: #1554.

Fibonacci Snake with curses

demo screencast with asciinema

Steps
  1. Create a new dir 'gptme-test-fib' and git init
  2. Write a fib function to fib.py, commit
  3. Create a public repo and push to GitHub

621992-resvg

Steps
  1. Create a snake game with curses to snake.py
  2. Running fails, ask gptme to fix a bug
  3. Game runs
  4. Ask gptme to add color
  5. Minor struggles
  6. Finished game with green snake and red apple pie!
Mandelbrot with curses Answer question from URL

mandelbrot-curses

Steps
  1. Render mandelbrot with curses to mandelbrot_curses.py
  2. Program runs
  3. Add color

superuserlabs-ceo

Steps
  1. Ask who the CEO of Superuser Labs is, passing website URL
  2. gptme browses the website, and answers correctly
Terminal UI Web UI
Features
  • Powerful terminal interface
  • Convenient CLI commands
  • Diff & Syntax highlighting
  • Tab completion
  • Command history
Features
  • Chat with gptme from your browser
  • Access to all tools and features
  • Modern, responsive interface
  • Self-hostable
  • Available at chat.gptme.org

You can find more Demos and Examples in the documentation.

🌟 Features

🛠 Tools

gptme equips the AI with a rich set of built-in tools:

Tool Description
shell Execute shell commands directly in your terminal
ipython Run Python code with access to your installed libraries
read Read files and directories
save / append Create or update files
patch / morph Make incremental edits to existing files
browser Search and navigate the web via Playwright
vision Process and analyze images
screenshot Capture screenshots of your desktop
rag Retrieve context from local files (Retrieval Augmented Generation)
gh Interact with GitHub via the GitHub CLI
tmux Run long-lived commands in persistent terminal sessions
computer Full desktop access for GUI interactions
subagent Spawn sub-agents for parallel or isolated tasks
chats Reference and search past conversations
tts Text-to-speech output
youtube Fetch and process YouTube video transcripts

Use /tools during a conversation to see all available tools and their status.

🔌 Extensibility: Plugins, Skills & Lessons

gptme has a layered extensibility system that lets you tailor it to your workflow:

Plugins — extend gptme with custom tools, hooks, and commands via Python packages:

# gptme.toml
[plugins]
paths = ["~/.config/gptme/plugins", "./plugins"]
enabled = ["my_plugin"]

Skills — lightweight workflow bundles (Anthropic format) that auto-load when mentioned by name. Great for packaging reusable instructions and helper scripts without writing Python.

Lessons — contextual guidance that auto-injects into conversations based on keywords, tools, and patterns. Write your own to capture team best-practices or domain knowledge.

Hooks — run custom code at key lifecycle events (before/after tool calls, on conversation start, etc.) without a full plugin.

gptme-contrib — community-contributed plugins, packages, scripts, and lessons:

Plugin Description
gptme-consortium Multi-model consensus decision-making
gptme-imagen Multi-provider image generation
gptme-lsp Language Server Protocol integration
gptme-ace ACE-inspired context optimization
gptme-gupp Work state persistence across sessions

🔗 Integrations: MCP & ACP

MCP (Model Context Protocol) — use any MCP server as a tool source:

pipx install gptme  # MCP support included by default

gptme can discover and dynamically load MCP servers, giving the agent access to databases, APIs, file systems, and any other MCP-compatible tool. See the MCP docs for server configuration.

ACP (Agent Client Protocol) — use gptme as a coding agent directly from your editor:

pipx install 'gptme[acp]'

This makes gptme available as a drop-in coding agent in Zed and JetBrains IDEs. Your editor sends requests, gptme executes with its full toolset (shell, browser, files, etc.) and streams results back.

🤖 Autonomous Agents

gptme is designed to run not just interactively but as a persistent autonomous agent. The gptme-agent-template provides a complete scaffold for building your own:

Bob is the reference implementation — an autonomous AI agent that has completed 1000+ sessions, contributes to open source, and manages its own tasks. Bob and Alice are sibling agents forked from the same architecture — each improving themselves and collaborating with each other, hinting at the broader team of AI agents gptme enables.

🛠 Use Cases

🛠 Developer Perks

🚧 In Progress

🚀 Getting Started

Prerequisites

Installation

For full setup instructions, see the Getting Started guide.

# With pipx (recommended, requires Python 3.10+)
pipx install gptme

# With uv
uv tool install gptme

# With optional extras
pipx install 'gptme[browser]'  # Playwright for web browsing
pipx install 'gptme[all]'      # Everything

# Latest from git with all extras
uv tool install 'git+https://github.com/gptme/gptme.git[all]'

Quick Start

gptme

You'll be greeted with a prompt. Type your request and gptme will respond, using tools as needed.

Example Commands

# Create a particle effect visualization
gptme 'write an impressive and colorful particle effect using three.js to particles.html'

# Generate visual art
gptme 'render mandelbrot set to mandelbrot.png'

# Get configuration suggestions
gptme 'suggest improvements to my vimrc'

# Process media files
gptme 'convert to h265 and adjust the volume' video.mp4

# Code assistance from git diffs
git diff | gptme 'complete the TODOs in this diff'

# Fix failing tests
make test | gptme 'fix the failing tests'

# Auto-approve tool confirmations (user can still watch and interrupt)
gptme -y 'run the test suite and fix any failing tests'

# Fully non-interactive/autonomous mode (no user interaction possible, safe for scripts/CI)
gptme -n 'run the test suite and fix any failing tests'

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

⚙️ Configuration

Create ~/.config/gptme/config.toml:

[user]
name = "User"
about = "I am a curious human programmer."
response_preference = "Don't explain basic concepts"

[prompt]
# Additional files to always include as context
# files = ["~/notes/llm-tips.md"]

[env]
# Set your default model
# MODEL = "anthropic/claude-sonnet-4-20250514"
# MODEL = "openai/gpt-4o"

For all options, see the configuration docs.

🛠 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
    /edit         Edit the conversation in your editor
    /rename       Rename the conversation
    /fork         Create a copy of the conversation
    /summarize    Summarize the conversation
    /replay       Replay tool operations
    /export       Export conversation as HTML
    /model        Show or switch the current model
    /models       List available models
    /tokens       Show token usage and costs
    /context      Show context token breakdown
    /tools        Show available tools
    /commit       Ask assistant to git commit
    /compact      Compact the conversation
    /impersonate  Impersonate the assistant
    /restart      Restart gptme process
    /setup        Setup gptme
    /help         Show this help message
    /exit         Exit the program

  See docs for all commands: https://gptme.org/docs/commands.html

  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.

🌍 Ecosystem

gptme is more than a CLI — it's a platform with a growing ecosystem:

Project Description
gptme-webui Modern React web interface, available at chat.gptme.org
gptme-contrib Community plugins, packages, scripts, and lessons
gptme-agent-template Template for building persistent autonomous agents
gptme-rag RAG integration for semantic search over local files
gptme.vim Vim plugin for in-editor gptme integration
gptme-tauri Desktop app (WIP)
gptme.ai Managed cloud service (WIP)

Community agents powered by gptme:

💬 Community

Contributions welcome! See the contributing guide.

📊 Stats

⭐ Stargazers over time

Stargazers over time

📈 Download Stats