gptme

📚 Table of Contents

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

📢 News

• 2026-09 - v0.34.0: Cross-harness memory (gptme-util memory, Claude Code & Codex integration), skills as slash commands, gptme service init for headless agents, context-scout pre-pass
• 2026-08 - v0.33.0: Hashline edit format, sandboxed Python/shell execution (Docker, Wasmtime), non-interactive exit taxonomy, gptme explain, server auth hardening
• 2026-07 - v0.32.0 & v0.32.1: Desktop app for Linux (AppImage), macOS, and Windows, with auto-updates since v0.32.1 — download here; ACP support, MCP server, Textual TUI; gptme.ai cloud service
• 2026-05 - gptme-plugin-registry created: central registry for plugin discovery
• 2026-02 - Scheduled dev pre-releases begin
• 2026-01 - gptme-agent-template v0.4: Bob has run extensively as an autonomous agent, 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

For more history, see the Timeline and Changelog.

🎥 Demos

[gptme-tui showing a conversation where gptme writes and runs fib.py]

[gptme web UI showing a demo conversation with a Python code block and its output]

[asciinema recording of gptme writing fib.py, committing it, and pushing to a new GitHub repo]

[asciinema recording of gptme rendering the Mandelbrot set in the terminal with curses]

[!NOTE] The terminal recordings above are from 2023 and show the classic CLI. More recordings are kept in the Demo archive, and more up-to-date walkthroughs are in the Examples.

🌟 Features

• 💻 Code execution
  • Executes code in your local environment with the shell and python tools.
• 🧩 Read, write, and change files
  • Makes incremental changes with the patch tool.
• 🌐 Search and browse the web
  • Can use a browser via Playwright with the 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
  • 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.
• 🗃️ Cross-harness memory
  • One local Markdown-based memory store shared by gptme, Claude Code, Codex, and any other harness.
  • gptme-util memory CLI — save, recall, search, supersede, and audit entries from any terminal.
  • Claude Code hook and Codex AGENTS.md integration included.
• 🤖 Support for many LLM providers
  • Anthropic (Claude), OpenAI (GPT), Google (Gemini), SpaceXAI (Grok), DeepSeek, and more.
  • Use OpenRouter or Requesty for access to 100+ models, or serve locally with Ollama, LM Studio, vLLM, or llama.cpp.
  • Bring your own subscription: use your existing ChatGPT Plus/Pro or SuperGrok plan instead of API keys (see providers).
  • Pick the right model per task — fast/cheap for triage, powerful for coding.
• 🌐 Web UI and REST API
  • Modern gptme-webui bundled with gptme-server and hosted at chat.gptme.org.
  • Server with REST API.
  • Standalone executable builds available with PyInstaller.
• 💻 Computer use
  • Give the assistant access to a full desktop, allowing it to interact with GUI applications.
• 🧠 Code intelligence
  • Structural code understanding with gptme-codegraph: call graphs, symbol extraction, and impact analysis powered by Tree-sitter. 10 MCP tools for codebase navigation.
• 🔊 Tool sounds — pleasant notification sounds for different tool operations.
  • Enable with GPTME_TOOL_SOUNDS=true.

🛠 Tools

gptme equips the AI with a rich set of built-in tools:

Tool	Description
shell	Execute shell commands directly in your terminal
ipython	Run Python code with access to your installed libraries
read	Read files and directories
save / append	Create or update files
patch / morph	Make incremental edits to existing files
browser	Search and navigate the web via Playwright
vision	Process and analyze images
screenshot	Capture screenshots of your desktop
rag	Retrieve context from local files (needs the gptme-rag package)
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
memory	Save and recall memory entries shared across harnesses
lessons	Look up contextual guidance and skills
todo	Keep a task list for the current conversation
mcp	Discover and load MCP servers at runtime

Use /tools during a conversation to see all available tools and their status.

🔌 Extensibility: Plugins, Skills & Lessons

gptme has a layered extensibility system that lets you tailor it to your workflow:

Plugins — extend gptme with custom tools, hooks, and commands via Python packages:

# gptme.toml
[plugins]
paths = ["~/.config/gptme/plugins", "./plugins"]
enabled = ["my_plugin"]

Skills — lightweight workflow bundles (Anthropic format) that auto-load when mentioned by name. Great for packaging reusable instructions and helper scripts without writing Python.

Lessons — contextual guidance that auto-injects into conversations based on keywords, tools, and patterns. Write your own to capture team best-practices or domain knowledge.

Hooks — run custom code at key lifecycle events (before/after tool calls, on conversation start, etc.) without a full plugin.

gptme-contrib — community-contributed plugins, packages, scripts, and lessons:

Plugin / Package	Description
gptme-codegraph	Structural code retrieval with tree-sitter: 10 MCP tools for parse, call graph, blast/impact analysis
gptme-consortium	Multi-model consensus decision-making
gptme-imagen	Multi-provider image generation
gptme-lsp	Language Server Protocol integration
gptme-ace	ACE-inspired context optimization
gptme-gupp	Work state persistence across sessions

🔗 Integrations: MCP & ACP

MCP (Model Context Protocol) — gptme works in both directions:

• MCP client: discover and load external MCP servers as gptme tools.
• MCP server: expose gptme's persistent shell, Python REPL, and file tools to Claude Desktop, Cursor, or any other MCP client.

pipx install gptme  # MCP support included by default

# Run gptme as an MCP server over stdio
gptme-mcp-server --tools shell,ipython,save,read

The server keeps shell and Python state across tool calls. See the MCP docs for a ready-to-paste Claude Desktop configuration and MCP client setup.

ACP (Agent Client Protocol) — use gptme as a coding agent directly from your editor:

pipx install 'gptme[acp]'

This makes gptme available as a drop-in coding agent in Zed and JetBrains IDEs. Your editor sends requests, gptme executes with its full toolset (shell, browser, files, etc.) and streams results back.

🤖 Autonomous Agents

gptme is designed to run not just interactively but as a persistent autonomous agent — an AI that runs continuously, remembers everything, and gets better over time. The gptme-agent-template provides a complete scaffold:

• Persistent workspace — git-tracked "brain" with journal, tasks, knowledge base, and lessons
• Run loops — scheduled (systemd/launchd) or event-driven autonomous operation
• Task management — structured task queue with YAML metadata and GTD-style workflows
• Meta-learning — lessons system captures behavioral patterns and improves over time
• Multi-agent coordination — file leases, message bus, and work claiming for concurrent agents
• External integrations — GitHub, email, Discord, Twitter, RSS, and more

# Create and run your own agent
gptme-agent create ~/ada --name Ada
cd ~/ada
gptme-agent install   # runs on a schedule
gptme-agent status    # check on it

Headless Agents with systemd

For quick setup of a gptme agent as a persistent systemd service on any Linux machine, use gptme service init:

# Generate a complete headless agent setup
gptme service init --name Ada --model anthropic/claude-haiku-4-5 --work-dir ~/ada

# Install and start on a daily timer
systemctl --user daemon-reload
systemctl --user enable --now Ada.timer

# Update the schedule (--force overwrites all generated files, including gptme.toml and startup script)
gptme service init --name Ada --work-dir ~/ada --timer-schedule hourly --force

This command scaffolds:

• systemd service unit — runs your agent in a user session
• Optional timer — schedule autonomous runs (hourly, daily, weekly, or on-demand)
• Startup script — runs one non-interactive gptme session per trigger and writes a durable journal entry
• Session prompt — prompt.md, the instruction the agent executes on every run
• Skeleton config — gptme.toml and AGENTS.md ready to customize

The scaffolded workspace is self-contained and runs as generated — edit prompt.md to say what the agent should do each run; all you need is gptme installed. Perfect for automation, monitoring, CI/CD orchestration, or running background agents on headless servers.

See Running agents autonomously for scheduling, monitoring, and guardrails.

Bob is the reference implementation — created in late 2024 and running autonomously since 2025, with 5,000+ merged pull requests to his name. Bob opens PRs, reviews code, fixes CI, manages his own task queue, maintains a growing set of behavioral lessons, posts on Twitter, responds on Discord, and writes blog posts.

Multiple specialized agents can run in parallel — e.g. Bob (engineering) and Alice (personal assistant & orchestration) — coordinating through shared infrastructure.

See the Autonomous Agents docs for the full guide.

🛡 Guardrails

Persistent agents need guardrails around the full loop, not just tool permissions:

• Input guardrails — structured task selectors in the agent workspace keep work focused and reduce thrashing on notifications or ambiguous work. Bob uses a CASCADE-style selector for this layer.
• Pre-action guardrails — lessons inject situational guidance before the agent acts.
• Output guardrails — hooks and pre-commit checks validate file changes before control returns to the user.

This stack is simple and composable: selectors improve work choice, lessons steer behavior, and checks verify the result. You can add evals on top later, but the baseline guardrail loop already exists.

🛠 Use Cases

• 🖥 Development: Write and run code faster with AI assistance.
• 🎯 Shell Expert: Get the right command using natural language (no more memorizing flags!).
• 📊 Data Analysis: Process and analyze data directly in your terminal.
• 🎓 Interactive Learning: Experiment with new technologies or codebases hands-on.
• 🤖 Agents & Tools: Build long-running autonomous agents for real work.
• 🔬 Research: Automate literature review, data collection, and analysis pipelines.

🛠 Developer Perks

• ⭐ One of the first agent CLIs created (Spring 2023) that is still in active development.
• 🧰 Easy to extend
  • Most functionality can be implemented with tools, hooks, and commands.
  • Plugins allow for easy packaging of extensions.
  • Trying to stay tiny — minimal core, extend as needed.
• 🧪 Extensive test suite, run on every PR.
• 🧹 Clean codebase, checked and formatted with ruff and mypy.
• 🤖 GitHub Bot to request changes from comments! (see #16)
  • Operates in this repo! (see #18 for example)
  • Runs entirely in GitHub Actions.
• 📊 Evaluation suite for testing capabilities of different models.
• 📝 gptme.vim for easy integration with vim.

🚧 In Progress

• ☁️ gptme.ai — managed cloud service for running gptme agents (early access; still self-hostable by running gptme-server + gptme-webui yourself)
• 🏆 Advanced evals for testing frontier capabilities

🚀 Getting Started

Prerequisites

• Python 3.11 or newer
• Credentials for at least one LLM provider:
  • Fastest no-credit-card path: start gptme, choose OpenRouter in the startup provider setup (browser OAuth), then run gptme "hello" -m openrouter/openrouter/free. On an existing setup, use /account setup openrouter inside a session. See Getting Started.
  • Subscriptions work too: sign in with your ChatGPT Plus/Pro or SuperGrok plan via gptme-auth openai-subscription or gptme-auth grok-subscription, no API key needed (see providers docs).
  • You can also set API keys manually for Anthropic (ANTHROPIC_API_KEY), OpenAI (OPENAI_API_KEY), OpenRouter (OPENROUTER_API_KEY), and other providers.
  • Local models need no key at all — run Ollama (or any OpenAI-compatible server) and use -m local/<model>, see providers docs.

Installation

For full setup instructions, see the Getting Started guide.

# With pipx (recommended, requires Python 3.11+)
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

# Latest from git with all extras
uv tool install 'git+https://github.com/gptme/gptme.git[all]'

Quick Start

gptme

You'll be greeted with a prompt. Type your request and gptme will respond, using tools as needed.

Example Commands

# Create a particle effect visualization
gptme 'write an impressive and colorful particle effect using three.js to particles.html'

# Generate visual art
gptme 'render mandelbrot set to mandelbrot.png'

# Get configuration suggestions
gptme 'suggest improvements to my vimrc'

# Process media files
gptme 'convert to h265 and adjust the volume' video.mp4

# Code assistance from git diffs
git diff | gptme 'complete the TODOs in this diff'

# Fix failing tests
make test | gptme 'fix the failing tests'

# Auto-approve tool confirmations (user can still watch and interrupt)
gptme -y 'run the test suite and fix any failing tests'

# Fully non-interactive: no prompts and no confirmations, for scripts/CI
# (every tool call runs unreviewed — scope its workspace and credentials accordingly)
gptme -n 'run the test suite and fix any failing tests'

# Machine-readable automation output (JSONL on stdout)
gptme --non-interactive --output-format json 'summarize the current git diff'

For more, see the Getting Started guide and the Examples in the documentation.

⚙️ Configuration

Create ~/.config/gptme/config.toml:

[user]
name = "User"
about = "I am a curious human programmer."
response_preference = "Don't explain basic concepts"

[prompt]
# Additional files to always include as context
# files = ["~/notes/llm-tips.md"]

[env]
# Set your default model
# MODEL = "anthropic/claude-sonnet-4-6"
# MODEL = "openai/gpt-5.6-sol"

For all options, see the configuration docs.

🛠 Usage

gptme                                   # start an interactive chat
gptme 'fix the failing tests'           # start with a prompt
gptme 'review this' main.py README.md   # include files (or URLs, or a GitHub PR) as context
gptme -m anthropic/claude-sonnet-4-6    # pick a model for this session
gptme -t read-only 'summarize the repo' # restrict which tools are available
gptme -y 'run the tests and fix them'   # auto-approve tool calls, stay in the loop
gptme -n 'summarize the git diff'       # fully non-interactive, for scripts and CI
gptme -r                                # resume the most recent conversation

During a conversation, /help lists the slash-commands — /undo, /backtrack, /tools, /tokens, /compact, /model, and more. gptme --help shows every flag, and gptme <subcommand> reaches the other CLIs (gptme tools list, gptme chats search, gptme skills list).

Full reference: CLI docs · commands · usage guide · automation

🌍 Ecosystem

gptme is more than a CLI — it's a platform with a growing ecosystem:

Project	Description
Web UI	Modern React web interface, available at chat.gptme.org
gptme-contrib	Community plugins, packages, scripts, and lessons
gptme-codegraph	Structural code retrieval with tree-sitter (10 MCP tools for code graph analysis)
gptme-agent-template	Template for building persistent autonomous agents
gptme-provider-template	Template for building custom LLM provider plugins
gptme-rag	RAG integration for semantic search over local files
gptme.vim	Vim plugin for in-editor gptme integration
Desktop app	Native app for Linux, macOS, Windows, and Android, built from this repo
gptme.ai	Managed cloud service (early access)

Community agents powered by gptme:

• Bob — autonomous AI agent, created late 2024 and running autonomously since 2025, contributes to open source and manages his own tasks
• Alice — personal assistant & agent orchestrator, forked from the same architecture

🏷️ Repository Badge

This repo is maintained with gptme. To show your repo is AI-assisted with gptme, add the badge below.

[![Built with gptme](https://gptme.org/badge.svg)](https://gptme.org)

💬 Community

• Discord — ask questions, share what you've built, discuss features
• GitHub Discussions — longer-form conversation and ideas
• X/Twitter — updates and announcements

Contributions welcome! See the contributing guide.

📊 Stats

⭐ Stargazers over time

[Stargazers over time]

Community and usage numbers (stars, downloads, contributors) are collected daily in gptme/stats.

📈 Download Stats

• PePy
• PyPiStats

📝 Citation

If you use gptme in your research, please cite it. The citation metadata lives in CITATION.cff (GitHub's "Cite this repository" button uses it). The Zenodo concept DOI identifies gptme across all archived versions. For reproducibility, cite the version-specific DOI from the Zenodo record for the release you used.

@software{gptme,
  author  = {Bjäreholt, Erik},
  title   = {gptme},
  year    = {2023},
  doi     = {10.5281/zenodo.22816651},
  url     = {https://github.com/gptme/gptme}
}

If you publish work that uses gptme, we'd love to hear about it on Discord.

🔗 Links

• Website
• Documentation
• GitHub
• Discord

❓ FAQ

Short answers with pointers into the documentation — the docs are the source of truth, this section just gets you to the right page.

What is gptme?

gptme is a personal AI agent that runs anywhere a terminal runs — your laptop, SSH sessions, tmux, headless servers, CI pipelines. It's provider-agnostic, local-first, and unconstrained: ships with shell, Python, web, vision, and everything else an agent needs. Pronounced /ʤiː piː tiː miː/ like "GPT-ME".

See Features for the full picture.

How does gptme compare to other AI coding assistants?

gptme is open source and model-agnostic, runs in any terminal, and is built for persistent autonomous agents whose memory lives in a git repo you own — not just interactive pair programming.

It's compared two ways: against coding agents (Claude Code, Codex, Cursor, Cline, Aider, OpenHands) and against persistent personal agents (OpenClaw, Hermes Agent, Grok Bot, Devin). See Alternatives for the maintained tables.

How do I install it?

curl -sSf https://gptme.ai/install.sh | sh   # auto-detects uv or pipx

Or install directly with pipx install gptme / uv tool install gptme (Python 3.11+). See Installation above, the Getting Started guide, and System dependencies for the extras individual tools need.

Do I need an API key?

No — you can also use a subscription you already pay for, or run a local model:

• Subscription: gptme-auth openai-subscription (ChatGPT Plus/Pro) or gptme-auth grok-subscription (SuperGrok), then e.g. gptme -m openai-subscription/<model>.
• Browser sign-in: pick OpenRouter in the startup setup (or /account setup openrouter).
• API keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, MOONSHOT_API_KEY, and more.
• Local models: no credentials at all, see below.

If setup is missing or broken, run gptme-doctor --fix. Full provider list, model prefixes, and setup details: Providers.

Can I run it fully locally?

Yes, against any OpenAI-compatible server (Ollama, LM Studio, vLLM, llama.cpp):

ollama pull llama3.2:3b && ollama serve
OPENAI_BASE_URL="http://127.0.0.1:11434/v1" gptme 'hello' -m local/llama3.2:3b

Put OPENAI_BASE_URL under [env] in ~/.config/gptme/config.toml to make it stick, or define a named provider entry. Note that small local models are significantly less capable at tool use. See Local & custom providers.

What tools does it have?

Shell, Python, file read/save/patch, browser, vision, computer use, tmux, subagents, MCP, and more — run /tools in a conversation to see what's active in your setup. See Tools for the full list and per-tool docs.

Does it support MCP?

Both directions: gptme consumes external MCP servers as tools, and gptme-mcp-server exposes gptme's session-backed shell, Python, and file tools to Claude Desktop, Cursor, and other MCP clients. See MCP. For editor integration (Zed, JetBrains), gptme also speaks ACP.

How do I teach it my conventions and make it remember?

• Lessons — guidance auto-included when keywords, patterns, or tools match.
• Skills — portable knowledge bundles in the Agent Skills format, loaded by name.
• Memory — cross-harness memory entries shared with Claude Code and Codex.
• Plugins and hooks — custom tools, commands, and lifecycle code.

How do I create an autonomous agent?

gptme-agent create ~/ada --name Ada   # workspace from the agent template
gptme-agent install                            # run on a schedule (systemd/launchd)

The workspace is the agent: identity, journal, tasks, and lessons live in a git repo you own. See Agents for the full workflow and guardrails, and Bob for an agent that has been running autonomously since 2025.

How do I use gptme in scripts and CI?

Use -n/--non-interactive, which skips confirmations and exits when done:

git diff | gptme -n 'review this diff for bugs'
gptme -n --output-format json 'summarize the failing tests'   # JSONL on stdout

See Automation for GitHub Actions, cron, and systemd recipes, or the GitHub bot for a ready-made @gptme PR/issue bot.

How do I configure it?

Configuration lives in ~/.config/gptme/config.toml (global), gptme.toml (per project), and per-conversation settings; environment variables and CLI flags override them. Set your default model with MODEL under [env], keep API keys in config.local.toml, and use -v for verbose logging. See Configuration.

Where can I find more resources?

• Website: gptme.org
• Documentation: docs.gptme.org
• Examples: Examples
• Downloads: Downloads
• Discord: Discord Community
• Twitter: @gptmeorg

---

Happy Agent Building! 🤖