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.
Install the CLI
The README recommends pipx; uv works too, and extras pull in the optional browser tooling.
# 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]' # EverythingStart a session
Run gptme with no arguments and you get a prompt. Type a request and it responds, reaching for its tools as needed.
gptmePick 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.
gptme "hello" -m openrouter/openrouter/freeTry the terminal UI
The Textual-based TUI adds queued prompts, collapsible tool output and a status bar with model, token usage and agent state.
pipx install 'gptme[tui]'Commands and code are distilled from the project's own documentation — always check the official repo for the latest.
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
How gptme compares
gptme alongside other open-source autonomous coding agents tools AI/TLDR tracks, ranked by GitHub stars.
| Tool | Stars | What it does |
|---|---|---|
| opencode | ★ 208k | OpenCode is an open source AI coding agent that runs in your terminal, with built-in build and plan agents and an optional desktop app. |
| Claude Code | ★ 146k | Anthropic's agentic coding tool for the terminal, IDE and GitHub: it understands your codebase, executes routine tasks, explains code and handles git workflows from natural-language commands. |
| OpenAI Codex | ★ 125k | OpenAI's cloud and CLI coding agent that writes features, fixes bugs, and proposes code changes across a repo, running tasks in parallel. |
| Gemini CLI | ★ 107k | An open-source command-line AI agent from Google that connects your terminal to Gemini models for reading code, editing files, running shell commands, and searching the web. |
| Pi | ★ 107k | Minimal terminal coding agent harness with four built-in tools, extended through TypeScript extensions, skills and prompt templates instead of forks. |
| autoresearch | ★ 96.2k | Karpathy's minimal harness that hands a coding agent a single-GPU LLM training script and lets it run fixed five-minute experiments, keeping or discarding each change on its own. |
| OpenHands | ★ 88.4k | An open-source AI software-development agent that plans tasks, edits files, runs commands, and tests code, usable from a terminal CLI, a local web GUI, or a Python SDK. |
| gptme | ★ 4.4k | A personal AI agent that runs anywhere a terminal runs |