The Principal Dev – Masterclass for Tech Leads

The Principal Dev – Masterclass for Tech Leads28-29 May

Join

gptme

/ʀiː piː tiː miː/
what does it stand for?

Getting Started β€’ Downloads β€’ Website β€’ Documentation

Build Status Docs Build Status Codecov
PyPI version PyPI - Downloads all-time PyPI - Downloads per day
Discord X.com
Powered by gptme

πŸ“œ A personal AI agent that runs anywhere a terminal runs β€” your laptop, ssh sessions, tmux, headless servers, CI pipelines.
Provider-agnostic, local-first, and unconstrained: ships with shell, Python, web, vision, and everything else an agent needs.
A great coding agent, but general-purpose enough to assist in all kinds of knowledge-work.

Free and open-source. Works with Anthropic, OpenAI, Google, xAI, DeepSeek, OpenRouter, or fully local via llama.cpp β€” your data, your models, your terminal.
A capable alternative to Claude Code, Codex, Cursor, and Warp β€” one of the first agent CLIs (Spring 2023), still in very active development.

πŸ“š Table of Contents

πŸ“’ News

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. We're working on automated demo generation: #1554.

Fibonacci Snake with curses

demo screencast with asciinema

Steps
  1. Create a new dir 'gptme-test-fib' and git init
  2. Write a fib function to fib.py, commit
  3. Create a public repo and push to GitHub

621992-resvg

Steps
  1. Create a snake game with curses to snake.py
  2. Running fails, ask gptme to fix a bug
  3. Game runs
  4. Ask gptme to add color
  5. Minor struggles
  6. Finished game with green snake and red apple pie!
Mandelbrot with curses Answer question from URL

mandelbrot-curses

Steps
  1. Render mandelbrot with curses to mandelbrot_curses.py
  2. Program runs
  3. Add color

superuserlabs-ceo

Steps
  1. Ask who the CEO of Superuser Labs is, passing website URL
  2. gptme browses the website, and answers correctly
Terminal UI Web UI
Features
  • Powerful terminal interface
  • Convenient CLI commands
  • Diff & Syntax highlighting
  • Tab completion
  • Command history
Features
  • Chat with gptme from your browser
  • Access to all tools and features
  • Modern, responsive interface
  • Self-hostable
  • Available at chat.gptme.org

You can find more Demos and Examples in the documentation.

🌟 Features

πŸ›  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 (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

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: 9 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) β€” use any MCP server as a tool source:

pipx install gptme  # MCP support included by default

gptme can discover and dynamically load MCP servers, giving the agent access to databases, APIs, file systems, and any other MCP-compatible tool. See the MCP docs for server configuration.

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:

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

Bob is the reference implementation β€” a production autonomous agent that's been running continuously since late 2024. 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:

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

πŸ›  Developer Perks

🚧 In Progress

πŸš€ Getting Started

Prerequisites

Installation

For full setup instructions, see the Getting Started guide.

# 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]'      # 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/autonomous mode (no user interaction possible, safe for scripts/CI)
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-20250514"
# MODEL = "openai/gpt-4o"

For all options, see the configuration docs.

πŸ›  Usage

$ gptme --help
Usage: gptme [OPTIONS] [PROMPTS]...

  gptme is a chat-CLI for LLMs, empowering them with tools to run shell
  commands, execute code, read and manipulate files, and more.

  If PROMPTS are provided, a new conversation will be started with it. PROMPTS
  can be chained with the '-' separator.

  The interface provides user commands that can be used to interact with the
  system.

  Available commands:
    /undo         Undo the last action
    /log          Show the conversation log
    /edit         Edit the conversation in your editor
    /rename       Rename the conversation
    /fork         Create a copy of the conversation
    /summarize    Summarize the conversation
    /replay       Replay tool operations
    /export       Export conversation as HTML
    /model        Show or switch the current model
    /models       List available models
    /tokens       Show token usage and costs
    /context      Show context token breakdown
    /tools        Show available tools
    /commit       Ask assistant to git commit
    /compact      Compact the conversation
    /impersonate  Impersonate the assistant
    /restart      Restart gptme process
    /setup        Setup gptme
    /help         Show this help message
    /exit         Exit the program

  See docs for all commands: https://gptme.org/docs/commands.html

  Keyboard shortcuts:
    Ctrl+X Ctrl+E  Edit prompt in your editor
    Ctrl+J         Insert a new line without executing the prompt

Options:
  --name TEXT            Name of conversation. Defaults to generating a random
                         name.
  -m, --model TEXT       Model to use, e.g. openai/gpt-5, anthropic/claude-
                         sonnet-4-20250514. If only provider given then a
                         default is used.
  -w, --workspace TEXT   Path to workspace directory. Pass '@log' to create a
                         workspace in the log directory.
  --agent-path TEXT      Path to agent workspace directory.
  -r, --resume           Load most recent conversation.
  -y, --no-confirm       Skip all confirmation prompts.
  -n, --non-interactive  Non-interactive mode. Implies --no-confirm.
  --output-format [text|json]
                         Output format for non-interactive mode. 'json'
                         emits one JSON object per line on stdout.
  --system TEXT          System prompt. Options: 'full', 'short', or something
                         custom.
  -t, --tools TEXT       Tools to allow as comma-separated list. Available:
                         append, browser, chats, choice, computer, gh,
                         ipython, morph, patch, rag, read, save, screenshot,
                         shell, subagent, tmux, vision.
  --tool-format TEXT     Tool format to use. Options: markdown, xml, tool
  --no-stream            Don't stream responses
  --show-hidden          Show hidden system messages.
  -v, --verbose          Show verbose output.
  --version              Show version and configuration information
  --help                 Show this message and exit.

Pair --non-interactive with --output-format json when stdout needs to be machine-readable, for example in CI or a supervising process. Use --resume to continue an existing automated conversation or pick up queued follow-up prompts without passing a new prompt.

🌍 Ecosystem

gptme is more than a CLI β€” it's a platform with a growing ecosystem:

Project Description
gptme-webui 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 (9 MCP tools for code graph analysis)
gptme-agent-template Template for building persistent autonomous agents
gptme-rag RAG integration for semantic search over local files
gptme.vim Vim plugin for in-editor gptme integration
gptme-tauri Desktop app (WIP)
gptme.ai Managed cloud service (WIP)

Community agents powered by gptme:

πŸ’¬ Community

Contributions welcome! See the contributing guide.

πŸ“Š Stats

⭐ Stargazers over time

Stargazers over time

πŸ“ˆ Download Stats

πŸ”— Links

❓ FAQ

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

How does gptme compare to other AI coding assistants?

Feature gptme Claude Code Cursor Warp
Environment Any terminal Terminal IDE Terminal
Autonomy Autonomous agents One-shot IDE-assisted Terminal AI
Multi-agent βœ… Concurrent agents ❌ ❌ ❌
Local-first βœ… Full support ❌ API required ❌ API required ❌ API required
Provider support βœ… 100+ models (OpenRouter/local) Anthropic/Bedrock/Vertex Anthropic/OpenAI/Google OpenAI (built-in)
MCP Support βœ… Built-in βœ… Built-in ❌ ❌
Plugin System βœ… Full plugins ❌ βœ… Extensions ❌
Web Browsing βœ… Playwright ❌ ❌ ❌
Vision βœ… Screenshots/Images βœ… βœ… ❌
Self-hosting βœ… Full control ❌ ❌ ❌

How do I install gptme?

Prerequisites: Python 3.10+

Installation:

pip install gptme
# or
pipx install gptme

First Run:

gptme

What AI providers does gptme support?

gptme supports multiple AI providers:

Provider Setup Features
Anthropic ANTHROPIC_API_KEY Claude models
OpenAI OPENAI_API_KEY GPT models
Google GEMINI_API_KEY Gemini models
xAI XAI_API_KEY Grok models
DeepSeek DEEPSEEK_API_KEY DeepSeek models
OpenRouter OPENROUTER_API_KEY Multi-provider gateway
llama.cpp Local server OpenAI-compatible local models

How do I use local models?

Use llama.cpp for fully local operation:

  1. Start llama.cpp server:
llama-server --model ./models/llama-3.gguf --port 8080
  1. Configure gptme:
export OPENAI_BASE_URL=http://localhost:8080/v1
gptme -m local/<model-name>

What tools does gptme have?

gptme ships with comprehensive tools:

How does the MCP integration work?

gptme has built-in MCP support:

Example MCP servers supported:

What is the Lessons system?

The Lessons system provides contextual guidance and best practices that are automatically included when relevant:

How do I create autonomous agents?

Use gptme-agent-template for persistent autonomous agents:

  1. Clone template:
git clone https://github.com/gptme/gptme-agent-template
  1. Configure agent:
# config.yaml
name: "MyAgent"
role: "Code reviewer"
schedule: "hourly"
  1. Run:
python agent.py

See Bob for an example autonomous agent that has been running continuously since late 2024.

What is the plugin system?

gptme has a full plugin system:

Example plugins:

How do I use gptme in CI/CD?

gptme runs in CI pipelines:

# GitHub Actions
- name: Run gptme
  run: |
    pip install gptme
    gptme --non-interactive "Review PR and suggest improvements"

What are the use cases?

gptme is general-purpose but excels at:

How do I configure gptme?

Configuration via environment variables:

# Provider selection
export GPTME_MODEL=anthropic/claude-sonnet-4-6

# API keys
export ANTHROPIC_API_KEY=your-key

# Logging level
export GPTME_LOG_LEVEL=INFO

How do I handle errors?

gptme is self-correcting:

Where can I find more resources?

Happy Terminal Agent Building! πŸ€–

Join libs.tech

...and unlock some superpowers

GitHub

We won't share your data with anyone else.