# gptme

> A personal AI agent that runs anywhere a terminal runs

- Category: AI Coding / Autonomous Coding Agents
- Language: Python
- Licence: MIT
- Repository: https://github.com/gptme/gptme
- Website: https://gptme.org/docs/
- Canonical page: https://ai-tldr.dev/tools/gptme/
- Updated: 2026-08-19

## In short

gptme is a personal AI agent you drive from the command line. It sits in the Autonomous Coding Agents category of the AI Coding tools and is open-source, written in Python and licensed MIT. To get started: install the CLI.

## Overview

gptme is a personal AI agent you drive from the command line. Instead of a chat window that hands back snippets to copy, it comes with the tools an agent actually needs — a shell, a Python interpreter, file editing, web browsing and vision — and uses them inside the loop, so it can write a script, run it, read the error and fix it without leaving the terminal.

Because it is just a terminal program, it runs in the places a desktop app cannot: over ssh, inside tmux, on a headless server, or as a step in a CI pipeline. It is provider-agnostic by design and works with Anthropic, OpenAI, Google, xAI, DeepSeek and OpenRouter, or fully locally through llama.cpp, so the model and the data boundary are both your choice.

The project dates to March 2023, making it one of the earliest agent CLIs, and it has grown an ecosystem around the core tool: a Textual TUI, a web UI, a server API, a plugin registry, and an agent template used to run long-lived autonomous agents on top of the same runtime. It is MIT-licensed and written in Python.

## What it does

- Built-in tool set — shell, Python, file edits, web browsing and vision — executed inside the agent loop rather than suggested as text
- Provider-agnostic: Anthropic, OpenAI, Google, xAI, DeepSeek and OpenRouter, or fully local models via llama.cpp
- Runs anywhere a terminal does — laptop, ssh session, tmux, headless server or a CI pipeline — with a non-interactive mode for scripting
- Sandboxed Python and shell execution via Docker or Wasmtime, added in v0.33.0 alongside the hashline edit format
- Extensible through plugins, skills and lessons, with a central plugin registry for discovery
- Integrates over MCP and ACP, and ships a Textual TUI (gptme-tui), a web UI and a server API alongside the plain CLI

## Getting started

gptme needs Python 3.10 or newer and credentials for at least one LLM provider. Local models through llama.cpp need no key at all.

1. Install the CLI

   The README recommends pipx; uv works too, and extras pull in the optional browser tooling.

```bash
# 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
```

2. Start a session

   Run gptme with no arguments and you get a prompt. Type a request and it responds, reaching for its tools as needed.

```bash
gptme
```

3. Pick a provider without a credit card

   The README's fastest path is OpenRouter: choose it in the startup provider setup (browser OAuth), then name a free model on the command line. Inside an existing session, use /account setup openrouter.

```bash
gptme "hello" -m openrouter/openrouter/free
```

4. Try the terminal UI

   The Textual-based TUI adds queued prompts, collapsible tool output and a status bar with model, token usage and agent state.

```bash
pipx install 'gptme[tui]'
```

## When to use it

- Give a coding agent a task on a remote machine over ssh, where an IDE-based assistant cannot reach
- Script a non-interactive agent step inside a CI pipeline and act on its exit status
- Work against a fully local model through llama.cpp when prompts and code must not leave the machine
- Build a persistent autonomous agent on top of the runtime using the agent template and plugin system

## Version history

- 2026-08-19 v0.33.0: Adds the hashline edit format and sandboxed Python and shell execution through Docker or Wasmtime. Also introduces a non-interactive exit taxonomy, a gptme explain command and hardened server auth.