gptme: A Terminal-Native AI Agent That Runs Wherever a Shell Does
Your agent in your terminal, equipped with local tools: writes code, uses the terminal, browses the web. Make your own persistent autonomous agent on top!
At a glance
- What is it?
- gptme is a Python-based, MIT-licensed CLI agent that combines shell, Python, web, and vision tools with support for multiple LLM providers, including local llama.cpp. Its strength is portability and extensibility, but its breadth means you must verify provider compatibility and tool behavior before relying on it.
- Who is it for?
- Adopt gptme if you live in a terminal, need an agent that works over SSH or in tmux, and want provider choice including local models. Skip it if you require a GUI-first experience or need guaranteed stability for production CI, since the project is under active development and some tools like desktop or cloud features are new.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What gptme Solves and Who It Targets
gptme positions itself as a personal AI agent that runs anywhere a terminal runs: a laptop, an SSH session, tmux, a headless server, or a CI pipeline. That is the core problem it addresses. Many coding agents are tied to a specific editor, a cloud service, or a desktop application. gptme instead ships as a CLI with a set of local tools, so the same agent can operate in environments where a graphical interface is impossible. The intended user is a developer or operator who already works from the command line and wants an agent that can write code, execute shell commands, and browse the web without leaving that context. The README also mentions general knowledge work, not just coding, which broadens the audience to anyone comfortable with a terminal and willing to configure an agent. It is not a product for someone who expects a polished, guided setup with no configuration.
The Mechanism: Tools, Providers, and Local-First Design
The README describes gptme as provider-agnostic and local-first. The agent ships with a set of tools: shell, Python, web, and vision, plus a tmux tool mentioned in the news timeline. The architecture is a loop where the model receives a prompt and can invoke these tools to act on the environment. The documentation mentions a redesigned server API in v0.28.0, suggesting that the agent can be driven programmatically, not just interactively. The local-first stance means your conversation data and tool execution stay on your machine, in contrast to cloud-hosted agents. The agent works with Anthropic, OpenAI, Google, xAI, DeepSeek, OpenRouter, or fully local via llama.cpp. That is a wide net. The trade-off is that each provider has different tool-calling conventions, so gptme must translate between them. The project has been evolving since early 2023, so the tool interface has likely matured, but the breadth of providers means you cannot assume every provider gets equal support.
Getting It Running: Installation and First Commands
The README points to a Getting Started page at gptme.org/docs/getting-started.html, but the exact commands are not in the provided material. What is clear is that gptme is on PyPI, so the typical install is via pip: pip install gptme. The project also offers downloads for a desktop app on Linux, macOS, and Windows, introduced in v0.32.1, with auto-updates. That desktop version is separate from the CLI. For the CLI, you would need to configure an API key for a provider, for example ANTHROPIC_API_KEY or OPENAI_API_KEY, or point it to a local llama.cpp server. The documentation site is the authoritative source for configuration keys. The release notes mention a form tool, cost tracking, and content-addressable storage in v0.31.0, which suggests that after installation you can track token spend and store artifacts by content hash. The README also shows a badge 'Built with gptme', implying that the project dogfoods itself, which is a good sign for real-world usage.
Extensibility: Plugins, Skills, Lessons, and MCP
gptme has a plugin system introduced in v0.30.0, plus a lessons system for contextual guidance and MCP support added in v0.28.0 and v0.29.0. Plugins allow you to add tools or modify behavior. The community repository gptme-contrib includes plugins for Twitter/X, Discord, email, and a multi-agent consortium. Skills and lessons are a way to inject project-specific knowledge or instructions. MCP (Model Context Protocol) support means you can connect to external MCP servers, and the v0.29.0 release added dynamic loading of MCP tools. This extensibility is a major differentiator: you are not locked into the built-in tool set. However, the plugin ecosystem is young, and you may need to write your own plugins if you need something niche. The README does not provide a plugin API example, so expect to read the documentation before extending.
Autonomous Agents and Guardrails
The README explicitly mentions autonomous agents as a feature, with a template repository gptme-agent-template and an example called Bob that has run extensive autonomous loops. This is different from an interactive assistant: the agent can run without human intervention, monitoring GitHub or performing background jobs. The v0.31.0 release added background jobs, which supports this use case. But autonomy raises safety questions. The README mentions guardrails as a listed feature, but the provided material does not describe what those guardrails are. That is a gap. If you plan to let gptme run unattended, you need to read the documentation on tool permissions and sandboxing. The morph tool for fast edits and auto-commit, added in v0.28.0, mean the agent can modify files and commit changes on its own. That is powerful but risky. The project does not appear to have a built-in container sandbox; it runs directly in your shell, so a misstep could affect your system. The tmux tool suggests it can manage terminal sessions, which is another vector for action.
Limitations and Cases Where gptme Is the Wrong Tool
The most obvious limitation is that gptme is a terminal agent. If you prefer a GUI or an editor-integrated assistant like Cursor, gptme is not that. The desktop app exists but is recent and may not have feature parity with the CLI. Another limitation is that the README's demos are from 2023 and the project acknowledges they are outdated, which means you cannot judge current behavior from those screencasts. The documentation is the only reliable source. The project is under very active development, with releases every few days (v0.33.1.dev20260903, dev20260831, dev20260827), so APIs and config may shift between versions. That is a maintenance cost. Also, because it supports many providers, you may hit provider-specific quirks that are not documented. For example, local llama.cpp models may not support all tool-calling formats, so the agent might fail to invoke tools correctly. If you need a turnkey solution with a fixed, supported model, gptme's flexibility is a burden, not a benefit.
Alternatives and How They Differ
The README names Claude Code, Codex, Cursor, and Warp as alternatives. Claude Code and Codex are coding agents from Anthropic and OpenAI respectively, typically tied to their own models and often to a specific editor or CLI. Cursor is an editor-centric AI assistant that embeds an agent in a GUI. Warp is a terminal that adds AI features. gptme's approach differs in two ways: it is provider-agnostic, so you can switch models without changing tools, and it is local-first, meaning your data is not sent to a proprietary cloud unless you choose a cloud provider. In contrast, Claude Code is designed to work with Claude models, and Codex is built around OpenAI models. If you want to use a local model via llama.cpp, gptme is a viable path, whereas those alternatives may not support that. The trade-off is that gptme may have fewer polished integrations with specific codebases or editors, since it is a general-purpose agent.
Maintenance, Upgrade Cost, and License Implications
gptme is licensed under MIT, which is permissive: you can use, modify, and redistribute it, even in proprietary products, as long as you retain the copyright notice. That is a low barrier for adoption. The release cadence is high, with development releases every few days, which means you get new features but also potential instability. The project has a changelog at gptme.org/docs/changelog.html, which is where you should check for breaking changes before upgrading. The v0.28.0 release redesigned the server API, which is a breaking change for anyone using the API programmatically. The v0.30.0 plugin system and v0.31.0 content-addressable storage are significant additions that may change how you store conversation data. There is also a desktop app with auto-updates, which simplifies upgrades for GUI users, but the CLI likely requires manual pip upgrades. The ecosystem includes gptme-webui, gptme-rag, and gptme.vim, which are separate projects you may need to track if you use them.
Editorial conclusion
Adopt gptme if you live in a terminal, need an agent that works over SSH or in tmux, and want provider choice including local models. Skip it if you require a GUI-first experience or need guaranteed stability for production CI, since the project is under active development and some tools like desktop or cloud features are new. Before committing, verify that your preferred model provider is supported in the current release, test the tool sandboxing behavior on your OS, and review the changelog for recent breaking changes.
Community notes