Gptme

<p align="center"> <img src="https://gptme.org/media/logo.png" width=150 /> </p> <h1 align="center">gptme</h1> <p align="center"> <i>/ʤiː piː tiː miː/</i> <br> _{<a href="https://gptme.org/docs/misc/acronyms.html">what does it stand for?</a>} </p> <!-- Links --> <p align="center"> <a href="https://gptme.org/docs/getting-started.html">Getting Started</a> • <a href="https://gptme.org/">Website</a> • <a href="https://gptme.org/docs/">Documentation</a> </p> <!-- Badges --> <p align="center"> <a href="https://github.com/gptme/gptme/actions/workflows/build.yml"> <img src="https://github.com/gptme/gptme/actions/workflows/build.yml/badge.svg" alt="Build Status" /> </a> <a href="https://github.com/gptme/gptme/actions/workflows/docs.yml"> <img src="https://github.com/gptme/gptme/actions/workflows/docs.yml/badge.svg" alt="Docs Build Status" /> </a> <a href="https://codecov.io/gh/gptme/gptme"> <img src="https://codecov.io/gh/gptme/gptme/graph/badge.svg?token=DYAYJ8EF41" alt="Codecov" /> </a> <br> <a href="https://pypi.org/project/gptme/"> <img src="https://img.shields.io/pypi/v/gptme" alt="PyPI version" /> </a> <a href="https://pepy.tech/project/gptme"> <img src="https://img.shields.io/pepy/dt/gptme" alt="PyPI - Downloads all-time" /> </a> <a href="https://pypistats.org/packages/gptme"> <img src="https://img.shields.io/pypi/dd/gptme?color=success" alt="PyPI - Downloads per day" /> </a> <br> <a href="https://discord.gg/NMaCmmkxWv"> <img src="https://img.shields.io/discord/1271539422017618012?logo=discord&style=social" alt="Discord" /> </a> <a href="https://x.com/gptmeorg"> <img src="https://img.shields.io/twitter/follow/gptmeorg?style=social" alt="X.com" /> </a> <br> <a href="https://gptme.org/docs/projects.html"> <img src="https://img.shields.io/badge/powered%20by-gptme%20%F0%9F%A4%96-5151f5?style=flat" alt="Powered by gptme" /> </a> </p> <p align="center"> 📜 A personal AI agent in your terminal, with tools to:<br/> run shell commands, write code, edit files, browse the web, use vision, and much more.<br/> A great coding agent, but general-purpose enough to assist in all kinds of knowledge-work. </p> <p align="center"> An unconstrained local free and open-source <a href="https://gptme.org/docs/alternatives.html">alternative</a> to Claude Code, Codex, Cursor Agents, etc.<br/> One of the first agent CLIs created (Spring 2023) — and still in very active development. </p>

📚 Table of Contents

• 📢 News
• 🎥 Demos
• 🌟 Features
  • 🛠 Tools
  • 🔌 Extensibility: Plugins, Skills & Lessons
  • 🔗 Integrations: MCP & ACP
  • 🤖 Autonomous Agents
  • 🛠 Use Cases
  • 🛠 Developer Perks
  • 🚧 In Progress
• 🚀 Getting Started
• 🛠 Usage
• 🌍 Ecosystem
• 💬 Community
• 📊 Stats
• 🔗 Links

📢 News

• Coming soon - gptme.ai service for running agents in the cloud; gptme desktop app for easy local use.
• 2026-01 - gptme-agent-template v0.4: Bob reaches 1700+ autonomous sessions, autonomous run loops, enhanced context generation
• 2025-12 - v0.31.0: Background jobs, form tool, cost tracking, content-addressable storage
• 2025-11 - v0.30.0: Plugin system, context compression, subagent planner mode
• 2025-10 - v0.29.0: Lessons system for contextual guidance, MCP discovery & dynamic loading, token awareness; Bob begins autonomous runs with GitHub monitoring
• 2025-08 - v0.28.0: MCP support, morph tool for fast edits, auto-commit, redesigned server API
• 2025-03 - v0.27.0: Pre-commit integration, macOS computer use, Claude 3.7 Sonnet, DeepSeek R1, local TTS with Kokoro
• 2025-01 - gptme-contrib created: community plugins including Twitter/X, Discord bot, email tools, consortium (multi-agent)
• 2024-12 - gptme-agent-template v0.3: Template for persistent agents
• 2024-11 - Ecosystem expansion: gptme-webui, gptme-rag, gptme.vim, Bob created (first autonomous agent)
• 2024-10 - First viral tweet bringing widespread attention
• 2024-08 - Show HN, Anthropic Claude support, tmux tool
• 2023-09 - Initial public release on HN, Reddit, Twitter
• 2023-03 - Initial commit - one of the first agent CLIs

<!-- source of truth: docs/timeline.rst and docs/changelog.rst -->

For more history, see the Timeline and Changelog.

🎥 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.

<table> <tr> <th>Fibonacci</th> <th>Snake with curses</th> </tr> <tr> <td width="50%">

<details> <summary>Steps</summary> <ol> <li> Create a new dir 'gptme-test-fib' and git init <li> Write a fib function to fib.py, commit <li> Create a public repo and push to GitHub </ol> </details> </td> <td width="50%">

<details> <summary>Steps</summary> <ol> <li> Create a snake game with curses to snake.py <li> Running fails, ask gptme to fix a bug <li> Game runs <li> Ask gptme to add color <li> Minor struggles <li> Finished game with green snake and red apple pie! </ol> </details> </td> </tr> <tr> <th>Mandelbrot with curses</th> <th>Answer question from URL</th> </tr> <tr> <td width="50%">

<details> <summary>Steps</summary> <ol> <li> Render mandelbrot with curses to mandelbrot_curses.py <li> Program runs <li> Add color </ol> </details> </td> <td width="25%">

<details> <summary>Steps</summary> <ol> <li> Ask who the CEO of Superuser Labs is, passing website URL <li> gptme browses the website, and answers correctly </ol> </details> </td> </tr> <tr> <th>Terminal UI</th> <th>Web UI</th> </tr> <tr> <td width="50%"> <!--[](https://asciinema.org/a/terminal-demo)--> <details> <summary>Features</summary> <ul> <li> Powerful terminal interface <li> Convenient CLI commands <li> Diff & Syntax highlighting <li> Tab completion <li> Command history </ul> </details> </td> <td width="50%"> <!--[](https://chat.gptme.org)--> <details> <summary>Features</summary> <ul> <li> Chat with gptme from your browser <li> Access to all tools and features <li> Modern, responsive interface <li> Self-hostable <li> Available at <a href="https://chat.gptme.org">chat.gptme.org</a> </ul> </details> </td> </tr> </table>

You can find more [Demos][docs-demos] and [Examples][docs-examples] in the [documentation][docs].

🌟 Features

• 💻 Code execution
  • Executes code in your local environment with the [shell][docs-tools-shell] and [python][docs-tools-python] tools.
• 🧩 Read, write, and change files
  • Makes incremental changes with the [patch][docs-tools-patch] tool.
• 🌐 Search and browse the web
  • Can use a browser via Playwright with the [browser][docs-tools-browser] tool.
• 👀 Vision
  • Can see images referenced in prompts, screenshots of your desktop, and web pages.
• 🔄 Self-correcting
  • Output is fed back to the assistant, allowing it to respond and self-correct.
• 📚 [Lessons system][docs-lessons]
  • Contextual guidance and best practices automatically included when relevant.
  • Keyword, tool, and pattern-based matching.
  • Adapts to interactive vs autonomous modes.
  • Extend with your own lessons and [skills][docs-skills].
• 🤖 Support for many LLM [providers][docs-providers]
  • Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok), DeepSeek, and more.
  • Use OpenRouter for access to 100+ models, or serve locally with llama.cpp.
• 🌐 Web UI and REST API
  • Modern web interface at chat.gptme.org ([gptme-webui])
  • Simple bu