Prerequisites

- Python 3.10 or newer - Credentials for at least one LLM provider: - Fastest no-credit-card path: start gptme, choose OpenRouter in the startup provider setup (browser OAuth), then run gptme "hello" -m openrouter/openrouter/free. On an existing setup, use /account setup openrouter inside a session. See [Getting Started][docs-getting-started]. - Subscriptions work too: sign in with your ChatGPT Plus/Pro or SuperGrok plan via gptme-auth openai-subscription or gptme-auth grok-subscription, no API key needed (see [providers docs][docs-providers]). - You can also set API keys manually for Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY), OpenRouter (OPENROUTER_API_KEY), and other providers. - Local models via llama.cpp need no key — see [providers docs][docs-providers].

With pipx (recommended, requires Python 3.10+)

pipx install gptme

Generate a complete headless agent setup

gptme service init --name my-agent --model gpt-4o-mini --work-dir ~/my-agent

Install and start on a daily timer

systemctl --user daemon-reload systemctl --user enable --now my-agent.timer

🚀 Getting Started

Installation

For full setup instructions, see the [Getting Started guide][docs-getting-started].

```sh

How do I install gptme?

Prerequisites: Python 3.10+

Installation: ```bash pip install gptme

🛠 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: Build long-running autonomous agents for real work.
• 🔬 Research: Automate literature review, data collection, and analysis pipelines.

Quick Start

gptme

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

Example Commands

```sh

🛠 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.
  --output-format [text|json]
                         Output format for non-interactive mode. 'json'
                         emits one JSON object per line on stdout.
  --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, vision.
  --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.

Pair `--non-interactive with --output-format json` when stdout needs to be machine-readable, for example in CI or a supervising process. Use `--resume` to continue an existing automated conversation or pick up queued follow-up prompts without passing a new prompt.

What are the use cases?

gptme is general-purpose but excels at:

• Coding: Write, refactor, debug code
• Research: Web browsing, data collection
• Automation: File management, CI tasks
• Documentation: Generate docs, summaries
• Testing: Write tests, run tests, fix failures
• DevOps: Server management, deployment

🎥 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][docs-examples]. We're working on automated demo generation: #1554.

3. Run: