# gptme

> A free, open-source personal AI agent that runs in any terminal, equipped with shell, Python, web browsing, vision, and autonomous agent capabilities.

gptme is a free and open-source personal AI agent that runs anywhere a terminal runs — laptops, SSH sessions, tmux, headless servers, and CI pipelines. Created in Spring 2023 by Erik Bjäreholt, it is provider-agnostic and local-first, shipping with shell, Python, web browsing, vision, and everything else an agent needs. The project is licensed under the MIT License and available on GitHub under the `gptme` organization.

## What It Is

gptme is a CLI-based AI agent framework in the category of autonomous coding and knowledge-work assistants. Its core job is to let users interact with large language models through a terminal while giving those models real tools to act on the local environment — executing shell commands, reading and writing files, browsing the web, taking screenshots, and spawning sub-agents. Unlike IDE-centric tools, gptme is designed to work in any environment where a terminal is available, including fully headless and automated contexts.

## Built-In Toolset

gptme ships with a rich set of built-in tools that the AI can invoke during a conversation:

- **shell** — execute shell commands directly in the terminal
- **ipython** — run Python code with access to installed libraries
- **read / save / append** — read and write files and directories
- **patch / morph** — make incremental or fast edits to existing files
- **browser** — search and navigate the web via Playwright
- **vision / screenshot** — process images and capture desktop screenshots
- **rag** — retrieve context from local files using Retrieval Augmented Generation
- **gh** — interact with GitHub via the GitHub CLI
- **tmux** — run long-lived commands in persistent terminal sessions
- **computer** — full desktop access for GUI interactions
- **subagent** — spawn sub-agents for parallel or isolated tasks
- **chats** — reference and search past conversations

## Provider Agnosticism and Local-First Design

gptme supports Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok), DeepSeek, and OpenRouter as LLM providers. It also supports fully local inference via `llama.cpp` with no API key required. Model routing lets users assign fast or cheap models to triage tasks and more powerful models to coding work. This local-first architecture means user data and models stay under user control.

## Autonomous Agent Architecture

Beyond interactive use, gptme is designed to run as a persistent autonomous agent. The `gptme-agent-template` provides a complete scaffold including a git-tracked workspace ("brain") with journal, tasks, knowledge base, and lessons; scheduled or event-driven run loops via systemd or launchd; structured task queues with GTD-style workflows; and multi-agent coordination through file leases and a message bus. The project's reference implementation, "Bob," has been running continuously since late 2024, opening PRs, reviewing code, fixing CI, and posting on social media.

## Extensibility: Plugins, Skills, Lessons, and MCP

gptme has a layered extensibility system. **Plugins** extend the tool with custom tools, hooks, and commands via Python packages. **Skills** are lightweight workflow bundles that auto-load when mentioned by name. **Lessons** inject contextual guidance into conversations based on keywords, tools, and patterns. **Hooks** run custom code at lifecycle events without requiring a full plugin. The community-contributed `gptme-contrib` repository includes plugins for multi-model consensus, image generation, Language Server Protocol integration, and work-state persistence. gptme also has built-in MCP (Model Context Protocol) support for dynamic discovery and loading of MCP servers, and ACP (Agent Client Protocol) support for use as a drop-in coding agent in Zed and JetBrains IDEs.

## Update: v0.31.0

The latest release is v0.31.0, published on December 15, 2025. It added background jobs, a form tool, cost tracking, and content-addressable storage. Prior notable releases include v0.30.0 (plugin system, context compression, subagent planner mode), v0.29.0 (lessons system, MCP discovery and dynamic loading, token awareness), and v0.28.0 (MCP support, morph tool, auto-commit, redesigned server API). A managed cloud service at gptme.ai and a desktop app (gptme-tauri) are listed as coming soon on the project homepage.

## Features
- Shell command execution
- Python code execution
- Web browsing via Playwright
- Vision and screenshot capture
- File read/write/patch/morph
- RAG for local files
- GitHub CLI integration
- tmux session management
- Computer use (full desktop access)
- Sub-agent spawning
- Autonomous agent mode
- Persistent agent workspace
- Multi-agent coordination
- MCP (Model Context Protocol) support
- ACP (Agent Client Protocol) support
- Plugin system
- Skills and Lessons system
- Hooks for lifecycle events
- Model routing
- Self-correcting output loop
- Web UI and REST API
- Non-interactive/CI mode
- JSONL machine-readable output
- Cost tracking
- Context compression
- Pre-commit integration
- Local inference via llama.cpp
- OpenRouter multi-provider gateway

## Integrations
Anthropic Claude, OpenAI GPT, Google Gemini, xAI Grok, DeepSeek, OpenRouter, llama.cpp, Playwright, GitHub CLI, tmux, MCP servers, Zed editor (ACP), JetBrains IDEs (ACP), Tree-sitter (gptme-codegraph), Discord, Twitter/X, Email, RSS, systemd, launchd, GitHub Actions

## Platforms
MACOS, WEB, API, JETBRAINS_PLUGIN, CLI

## Pricing
Open Source

## Version
v0.31.0

## Links
- Website: https://gptme.org/
- Documentation: https://gptme.org/docs/
- Repository: https://github.com/gptme/gptme
- EveryDev.ai: https://www.everydev.ai/tools/gptme