gptme - agent in your terminal

gptme

/ʤiː piː tiː miː/

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

📜 Personal AI agent in your terminal, with tools so it can:
Use the terminal, run code, edit files, browse the web, use vision, and much more;
a great coding agent, but is general-purpose to assists 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) that is still in active development.

📚 Table of Contents

📢 News

For more history, see the Timeline and Changelog.

🎥 Demos

Note

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

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

🛠 Use Cases

🛠 Developer perks

🚧 In progress

🚀 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
    /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        List or switch 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.

📊 Stats

⭐ Stargazers over time

Stargazers over time

📈 Download Stats