{"id":26182508,"url":"https://github.com/gptme/gptme","last_synced_at":"2026-04-02T23:52:25.108Z","repository":{"id":158932733,"uuid":"618514446","full_name":"gptme/gptme","owner":"gptme","description":"Your agent in your terminal, equipped with local tools: writes code, uses the terminal, browses the web, vision.","archived":false,"fork":false,"pushed_at":"2025-05-10T09:07:19.000Z","size":15405,"stargazers_count":3780,"open_issues_count":90,"forks_count":305,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-05-10T10:20:01.388Z","etag":null,"topics":["ai-agents","ai-assistant","anthropic","chatbot","chatgpt","cli","code-generation","llamacpp","llm","llm-agent","llm-apps","openai","openrouter","rag"],"latest_commit_sha":null,"homepage":"https://gptme.org/docs/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gptme.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["ErikBjare"],"patreon":"erikbjare"}},"created_at":"2023-03-24T16:25:01.000Z","updated_at":"2025-05-10T09:49:10.000Z","dependencies_parsed_at":"2023-05-31T22:00:33.323Z","dependency_job_id":"3b8855b7-9ff0-4423-8071-817242bcf65a","html_url":"https://github.com/gptme/gptme","commit_stats":{"total_commits":658,"total_committers":5,"mean_commits":131.6,"dds":0.006079027355623046,"last_synced_commit":"81708e6a2e275f134ab5931f51f6efeefb013f8a"},"previous_names":["erikbjare/gptme","erikbjare/gpt-playground","gptme/gptme"],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gptme%2Fgptme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gptme%2Fgptme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gptme%2Fgptme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gptme%2Fgptme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gptme","download_url":"https://codeload.github.com/gptme/gptme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253625853,"owners_count":21938209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-assistant","anthropic","chatbot","chatgpt","cli","code-generation","llamacpp","llm","llm-agent","llm-apps","openai","openrouter","rag"],"created_at":"2025-03-11T22:01:56.128Z","updated_at":"2026-04-02T23:52:25.081Z","avatar_url":"https://github.com/gptme.png","language":"Python","funding_links":["https://github.com/sponsors/ErikBjare","https://patreon.com/erikbjare"],"categories":["🚀 AI Tools for Vim, Neovim, and Terminal","CLIs","Python","cli","Table of Contents","Personal Assistants \u0026 Conversational Agents","🧠 AI Applications \u0026 Platforms","Terminal-native coding agents","chatgpt","UIs","Chatbots \u0026 Virtual Companions","4. Agentic AI \u0026 Multi-Agent Systems"],"sub_categories":["Agent","Virtual Assistants","Tools","Open Source","Command-line(shell) interface"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://gptme.org/media/logo.png\" width=150 /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003egptme\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ci\u003e/ʤiː piː tiː miː/\u003c/i\u003e\n\u003cbr\u003e\n\u003csub\u003e\u003ca href=\"https://gptme.org/docs/misc/acronyms.html\"\u003ewhat does it stand for?\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003c!-- Links --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://gptme.org/docs/getting-started.html\"\u003eGetting Started\u003c/a\u003e\n  •\n  \u003ca href=\"https://gptme.org/\"\u003eWebsite\u003c/a\u003e\n  •\n  \u003ca href=\"https://gptme.org/docs/\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- Badges --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/gptme/gptme/actions/workflows/build.yml\"\u003e\n    \u003cimg src=\"https://github.com/gptme/gptme/actions/workflows/build.yml/badge.svg\" alt=\"Build Status\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/gptme/gptme/actions/workflows/docs.yml\"\u003e\n    \u003cimg src=\"https://github.com/gptme/gptme/actions/workflows/docs.yml/badge.svg\" alt=\"Docs Build Status\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/gptme/gptme\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/gptme/gptme/graph/badge.svg?token=DYAYJ8EF41\" alt=\"Codecov\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://pypi.org/project/gptme/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/gptme\" alt=\"PyPI version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pepy.tech/project/gptme\"\u003e\n    \u003cimg src=\"https://img.shields.io/pepy/dt/gptme\" alt=\"PyPI - Downloads all-time\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypistats.org/packages/gptme\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/dd/gptme?color=success\" alt=\"PyPI - Downloads per day\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://discord.gg/NMaCmmkxWv\"\u003e\n    \u003cimg src=\"https://img.shields.io/discord/1271539422017618012?logo=discord\u0026style=social\" alt=\"Discord\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://x.com/gptmeorg\"\u003e\n    \u003cimg src=\"https://img.shields.io/twitter/follow/gptmeorg?style=social\" alt=\"X.com\" /\u003e\n  \u003c/a\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://gptme.org/docs/projects.html\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/powered%20by-gptme%20%F0%9F%A4%96-5151f5?style=flat\" alt=\"Powered by gptme\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n📜 A personal AI agent in your terminal, with tools to:\u003cbr/\u003e\nrun shell commands, write code, edit files, browse the web, use vision, and much more.\u003cbr/\u003e\nA great coding agent, but general-purpose enough to assist in all kinds of knowledge-work.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nAn unconstrained local free and open-source \u003ca href=\"https://gptme.org/docs/alternatives.html\"\u003ealternative\u003c/a\u003e to Claude Code, Codex, Cursor Agents, etc.\u003cbr/\u003e\nOne of the first agent CLIs created (Spring 2023) — and still in very active development.\n\u003c/p\u003e\n\n## 📚 Table of Contents\n\n- 📢 [News](#news)\n- 🎥 [Demos](#-demos)\n- 🌟 [Features](#-features)\n  - [🛠 Tools](#-tools)\n  - [🔌 Extensibility: Plugins, Skills \u0026 Lessons](#-extensibility-plugins-skills--lessons)\n  - [🔗 Integrations: MCP \u0026 ACP](#-integrations-mcp--acp)\n  - [🤖 Autonomous Agents](#-autonomous-agents)\n  - [🛠 Use Cases](#-use-cases)\n  - [🛠 Developer Perks](#-developer-perks)\n  - [🚧 In Progress](#-in-progress)\n- 🚀 [Getting Started](#-getting-started)\n- 🛠 [Usage](#-usage)\n- 🌍 [Ecosystem](#-ecosystem)\n- 💬 [Community](#-community)\n- 📊 [Stats](#-stats)\n- 🔗 [Links](#-links)\n\n## 📢 News\n\n- **Coming soon** - [gptme.ai](https://gptme.ai) service for running agents in the cloud; [gptme desktop](https://github.com/gptme/gptme-tauri) app for easy local use.\n- **2026-01** - [gptme-agent-template](https://github.com/gptme/gptme-agent-template) v0.4: [Bob](https://github.com/TimeToBuildBob) reaches 1700+ autonomous sessions, autonomous run loops, enhanced context generation\n- **2025-12** - [v0.31.0](https://github.com/gptme/gptme/releases/tag/v0.31.0): Background jobs, form tool, cost tracking, content-addressable storage\n- **2025-11** - [v0.30.0](https://github.com/gptme/gptme/releases/tag/v0.30.0): Plugin system, context compression, subagent planner mode\n- **2025-10** - [v0.29.0](https://github.com/gptme/gptme/releases/tag/v0.29.0): Lessons system for contextual guidance, MCP discovery \u0026 dynamic loading, token awareness; [Bob](https://github.com/TimeToBuildBob) begins autonomous runs with GitHub monitoring\n- **2025-08** - [v0.28.0](https://github.com/gptme/gptme/releases/tag/v0.28.0): MCP support, morph tool for fast edits, auto-commit, redesigned server API\n- **2025-03** - [v0.27.0](https://github.com/gptme/gptme/releases/tag/v0.27.0): Pre-commit integration, macOS computer use, Claude 3.7 Sonnet, DeepSeek R1, local TTS with Kokoro\n- **2025-01** - [gptme-contrib](https://github.com/gptme/gptme-contrib) created: community plugins including Twitter/X, Discord bot, email tools, consortium (multi-agent)\n- **2024-12** - [gptme-agent-template](https://github.com/gptme/gptme-agent-template) v0.3: Template for persistent agents\n- **2024-11** - Ecosystem expansion: [gptme-webui](https://github.com/gptme/gptme-webui), [gptme-rag](https://github.com/gptme/gptme-rag), [gptme.vim](https://github.com/gptme/gptme.vim), [Bob](https://github.com/TimeToBuildBob) created (first autonomous agent)\n- **2024-10** - [First viral tweet](https://x.com/rohanpaul_ai/status/1841999030999470326) bringing widespread attention\n- **2024-08** - [Show HN](https://news.ycombinator.com/item?id=41204256), Anthropic Claude support, tmux tool\n- **2023-09** - [Initial public release](https://news.ycombinator.com/item?id=37394845) on HN, [Reddit](https://www.reddit.com/r/LocalLLaMA/comments/16atlia/), [Twitter](https://x.com/ErikBjare/status/1699097896451289115)\n- **2023-03** - [Initial commit](https://github.com/gptme/gptme/commit/d00e9aae68cbd6b89bbc474ed7721d08796dc) - one of the first agent CLIs\n\n\n\u003c!-- source of truth: docs/timeline.rst and docs/changelog.rst --\u003e\nFor more history, see the [Timeline](https://gptme.org/docs/timeline.html) and [Changelog](https://gptme.org/docs/changelog.html).\n\n## 🎥 Demos\n\n\u003e [!NOTE]\n\u003e The screencasts below are from 2023. gptme has evolved a lot since then!\n\u003e For up-to-date examples and screenshots, see the [Documentation][docs-examples].\n\u003e We're working on automated demo generation: [#1554](https://github.com/gptme/gptme/issues/1554).\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eFibonacci\u003c/th\u003e\n    \u003cth\u003eSnake with curses\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n\n[![demo screencast with asciinema](https://github.com/ErikBjare/gptme/assets/1405370/5dda4240-bb7d-4cfa-8dd1-cd1218ccf571)](https://asciinema.org/a/606375)\n\n  \u003cdetails\u003e\n  \u003csummary\u003eSteps\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e Create a new dir 'gptme-test-fib' and git init\n    \u003cli\u003e Write a fib function to fib.py, commit\n    \u003cli\u003e Create a public repo and push to GitHub\n  \u003c/ol\u003e\n  \u003c/details\u003e\n\n  \u003c/td\u003e\n\n  \u003ctd width=\"50%\"\u003e\n\n[![621992-resvg](https://github.com/ErikBjare/gptme/assets/1405370/72ac819c-b633-495e-b20e-2e40753ec376)](https://asciinema.org/a/621992)\n\n  \u003cdetails\u003e\n  \u003csummary\u003eSteps\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e Create a snake game with curses to snake.py\n    \u003cli\u003e Running fails, ask gptme to fix a bug\n    \u003cli\u003e Game runs\n    \u003cli\u003e Ask gptme to add color\n    \u003cli\u003e Minor struggles\n    \u003cli\u003e Finished game with green snake and red apple pie!\n  \u003c/ol\u003e\n  \u003c/details\u003e\n  \u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n  \u003cth\u003eMandelbrot with curses\u003c/th\u003e\n  \u003cth\u003eAnswer question from URL\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n  \u003ctd width=\"50%\"\u003e\n\n[![mandelbrot-curses](https://github.com/ErikBjare/gptme/assets/1405370/570860ac-80bd-4b21-b8d1-da187d7c1a95)](https://asciinema.org/a/621991)\n\n  \u003cdetails\u003e\n  \u003csummary\u003eSteps\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e Render mandelbrot with curses to mandelbrot_curses.py\n    \u003cli\u003e Program runs\n    \u003cli\u003e Add color\n  \u003c/ol\u003e\n  \u003c/details\u003e\n\n  \u003c/td\u003e\n\n  \u003ctd width=\"25%\"\u003e\n\n[![superuserlabs-ceo](https://github.com/ErikBjare/gptme/assets/1405370/bae45488-f4ed-409c-a656-0c5218877de2)](https://asciinema.org/a/621997)\n\n  \u003cdetails\u003e\n  \u003csummary\u003eSteps\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e Ask who the CEO of Superuser Labs is, passing website URL\n    \u003cli\u003e gptme browses the website, and answers correctly\n  \u003c/ol\u003e\n  \u003c/details\u003e\n  \u003c/td\u003e\n  \u003c/tr\u003e\n\n  \u003ctr\u003e\n    \u003cth\u003eTerminal UI\u003c/th\u003e\n    \u003cth\u003eWeb UI\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n  \u003ctd width=\"50%\"\u003e\n\n\u003c!--[![terminal-ui](https://github.com/ErikBjare/gptme/assets/1405370/terminal-ui-demo)](https://asciinema.org/a/terminal-demo)--\u003e\n\n  \u003cdetails\u003e\n  \u003csummary\u003eFeatures\u003c/summary\u003e\n  \u003cul\u003e\n    \u003cli\u003e Powerful terminal interface\n    \u003cli\u003e Convenient CLI commands\n    \u003cli\u003e Diff \u0026 Syntax highlighting\n    \u003cli\u003e Tab completion\n    \u003cli\u003e Command history\n  \u003c/ul\u003e\n  \u003c/details\u003e\n\n  \u003c/td\u003e\n  \u003ctd width=\"50%\"\u003e\n\n\u003c!--[![web-ui](https://github.com/ErikBjare/gptme/assets/1405370/web-ui-demo)](https://chat.gptme.org)--\u003e\n\n  \u003cdetails\u003e\n  \u003csummary\u003eFeatures\u003c/summary\u003e\n  \u003cul\u003e\n    \u003cli\u003e Chat with gptme from your browser\n    \u003cli\u003e Access to all tools and features\n    \u003cli\u003e Modern, responsive interface\n    \u003cli\u003e Self-hostable\n    \u003cli\u003e Available at \u003ca href=\"https://chat.gptme.org\"\u003echat.gptme.org\u003c/a\u003e\n  \u003c/ul\u003e\n  \u003c/details\u003e\n\n  \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nYou can find more [Demos][docs-demos] and [Examples][docs-examples] in the [documentation][docs].\n\n## 🌟 Features\n\n- 💻 **Code execution**\n  - Executes code in your local environment with the [shell][docs-tools-shell] and [python][docs-tools-python] tools.\n- 🧩 **Read, write, and change files**\n  - Makes incremental changes with the [patch][docs-tools-patch] tool.\n- 🌐 **Search and browse the web**\n  - Can use a browser via Playwright with the [browser][docs-tools-browser] tool.\n- 👀 **Vision**\n  - Can see images referenced in prompts, screenshots of your desktop, and web pages.\n- 🔄 **Self-correcting**\n  - Output is fed back to the assistant, allowing it to respond and self-correct.\n- 📚 **[Lessons system][docs-lessons]**\n  - Contextual guidance and best practices automatically included when relevant.\n  - Keyword, tool, and pattern-based matching.\n  - Adapts to interactive vs autonomous modes.\n  - Extend with your own lessons and [skills][docs-skills].\n- 🤖 **Support for many LLM [providers][docs-providers]**\n  - Anthropic (Claude), OpenAI (GPT), Google (Gemini), xAI (Grok), DeepSeek, and more.\n  - Use OpenRouter for access to 100+ models, or serve locally with `llama.cpp`.\n- 🌐 **Web UI and REST API**\n  - Modern web interface at [chat.gptme.org](https://chat.gptme.org) ([gptme-webui])\n  - Simple built-in web UI included in the Python package.\n  - [Server][docs-server] with REST API.\n  - Standalone executable builds available with PyInstaller.\n- 💻 **[Computer use][docs-tools-computer]** (see [#216](https://github.com/gptme/gptme/issues/216))\n  - Give the assistant access to a full desktop, allowing it to interact with GUI applications.\n- 🔊 **Tool sounds** — pleasant notification sounds for different tool operations.\n  - Enable with `GPTME_TOOL_SOUNDS=true`.\n\n### 🛠 Tools\n\ngptme equips the AI with a rich set of built-in tools:\n\n| Tool | Description |\n|------|-------------|\n| `shell` | Execute shell commands directly in your terminal |\n| `ipython` | Run Python code with access to your installed libraries |\n| `read` | Read files and directories |\n| `save` / `append` | Create or update files |\n| `patch` / `morph` | Make incremental edits to existing files |\n| `browser` | Search and navigate the web via Playwright |\n| `vision` | Process and analyze images |\n| `screenshot` | Capture screenshots of your desktop |\n| `rag` | Retrieve context from local files (Retrieval Augmented Generation) |\n| `gh` | Interact with GitHub via the GitHub CLI |\n| `tmux` | Run long-lived commands in persistent terminal sessions |\n| `computer` | Full desktop access for GUI interactions |\n| `subagent` | Spawn sub-agents for parallel or isolated tasks |\n| `chats` | Reference and search past conversations |\n\nUse `/tools` during a conversation to see all available tools and their status.\n\n### 🔌 Extensibility: Plugins, Skills \u0026 Lessons\n\ngptme has a layered extensibility system that lets you tailor it to your workflow:\n\n**[Plugins][docs-plugins]** — extend gptme with custom tools, hooks, and commands via Python packages:\n\n```toml\n# gptme.toml\n[plugins]\npaths = [\"~/.config/gptme/plugins\", \"./plugins\"]\nenabled = [\"my_plugin\"]\n```\n\n**[Skills][docs-skills]** — lightweight workflow bundles (Anthropic format) that auto-load when mentioned by name. Great for packaging reusable instructions and helper scripts without writing Python.\n\n**[Lessons][docs-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.\n\n**[Hooks][docs-hooks]** — run custom code at key lifecycle events (before/after tool calls, on conversation start, etc.) without a full plugin.\n\n**[gptme-contrib][gptme-contrib]** — community-contributed plugins, packages, scripts, and lessons:\n\n| Plugin | Description |\n|--------|-------------|\n| [gptme-consortium](https://github.com/gptme/gptme-contrib/tree/master/plugins/gptme-consortium) | Multi-model consensus decision-making |\n| [gptme-imagen](https://github.com/gptme/gptme-contrib/tree/master/plugins/gptme-imagen) | Multi-provider image generation |\n| [gptme-lsp](https://github.com/gptme/gptme-contrib/tree/master/plugins/gptme-lsp) | Language Server Protocol integration |\n| [gptme-ace](https://github.com/gptme/gptme-contrib/tree/master/plugins/gptme-ace) | ACE-inspired context optimization |\n| [gptme-gupp](https://github.com/gptme/gptme-contrib/tree/master/plugins/gptme-gupp) | Work state persistence across sessions |\n\n### 🔗 Integrations: MCP \u0026 ACP\n\n**[MCP (Model Context Protocol)][docs-mcp]** — use any MCP server as a tool source:\n\n```sh\npipx install gptme  # MCP support included by default\n```\n\ngptme 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][docs-mcp] for server configuration.\n\n**[ACP (Agent Client Protocol)][docs-acp]** — use gptme as a coding agent directly from your editor:\n\n```sh\npipx install 'gptme[acp]'\n```\n\nThis makes gptme available as a drop-in coding agent in [Zed](https://zed.dev/) and JetBrains IDEs. Your editor sends requests, gptme executes with its full toolset (shell, browser, files, etc.) and streams results back.\n\n### 🤖 Autonomous Agents\n\ngptme 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][agent-template] provides a complete scaffold:\n\n- **Persistent workspace** — git-tracked \"brain\" with journal, tasks, knowledge base, and lessons\n- **Run loops** — scheduled (systemd/launchd) or event-driven autonomous operation\n- **Task management** — structured task queue with YAML metadata and GTD-style workflows\n- **Meta-learning** — lessons system captures behavioral patterns and improves over time\n- **Multi-agent coordination** — file leases, message bus, and work claiming for concurrent agents\n- **External integrations** — GitHub, email, Discord, Twitter, RSS, and more\n\n```sh\n# Create and run your own agent\ngptme-agent create ~/my-agent --name MyAgent\ngptme-agent install   # runs on a schedule\ngptme-agent status    # check on it\n```\n\n[**Bob**](https://github.com/TimeToBuildBob) is the reference implementation — a production autonomous agent with 1700+ completed sessions. Bob opens PRs, reviews code, fixes CI, manages his own task queue, maintains 100+ behavioral lessons, posts on [Twitter](https://twitter.com/TimeToBuildBob), responds on Discord, and writes [blog posts](https://timetobuildbob.github.io/).\n\nMultiple specialized agents can run in parallel — e.g. Bob (engineering) and [Alice](https://github.com/TimeToLearnAlice) (personal assistant \u0026 orchestration) — coordinating through shared infrastructure.\n\nSee the [Autonomous Agents docs](https://gptme.org/docs/agents.html) for the full guide.\n\n### 🛠 Use Cases\n\n- 🖥 **Development:** Write and run code faster with AI assistance.\n- 🎯 **Shell Expert:** Get the right command using natural language (no more memorizing flags!).\n- 📊 **Data Analysis:** Process and analyze data directly in your terminal.\n- 🎓 **Interactive Learning:** Experiment with new technologies or codebases hands-on.\n- 🤖 **Agents \u0026 Tools:** Build long-running autonomous agents for real work.\n- 🔬 **Research:** Automate literature review, data collection, and analysis pipelines.\n\n### 🛠 Developer Perks\n\n- ⭐ One of the first agent CLIs created (Spring 2023) that is still in active development.\n- 🧰 **Easy to extend**\n  - Most functionality can be implemented with [tools][docs-tools], [hooks][docs-hooks], and [commands][docs-commands].\n  - [Plugins][docs-plugins] allow for easy packaging of extensions.\n  - Trying to stay [tiny][docs-arewetiny] — minimal core, extend as needed.\n- 🧪 Extensive testing, high coverage.\n- 🧹 Clean codebase, checked and formatted with `mypy`, `ruff`, and `pyupgrade`.\n- 🤖 [GitHub Bot][docs-bot] to request changes from comments! (see [#16](https://github.com/gptme/gptme/issues/16))\n  - Operates in this repo! (see [#18](https://github.com/gptme/gptme/issues/18) for example)\n  - Runs entirely in GitHub Actions.\n- 📊 [Evaluation suite][docs-evals] for testing capabilities of different models.\n- 📝 [gptme.vim][gptme.vim] for easy integration with vim.\n\n### 🚧 In Progress\n\n- 🖥 **[gptme-tauri](https://github.com/gptme/gptme-tauri)** — desktop app wrapping gptme for easy local use (WIP)\n- ☁️ **[gptme.ai](https://gptme.ai)** — managed cloud service for running gptme agents (WIP; still self-hostable by running `gptme-server` + `gptme-webui` yourself)\n- 🌳 Tree-based conversation structure (see [#17](https://github.com/gptme/gptme/issues/17))\n- 📜 RAG to automatically include context from local files (see [#59](https://github.com/gptme/gptme/issues/59))\n- 🏆 Advanced evals for testing frontier capabilities\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Python 3.10 or newer\n- An API key for at least one LLM provider:\n  - [Anthropic](https://console.anthropic.com/) (set `ANTHROPIC_API_KEY`)\n  - [OpenAI](https://platform.openai.com/) (set `OPENAI_API_KEY`)\n  - [OpenRouter](https://openrouter.ai/) (set `OPENROUTER_API_KEY`)\n  - Local models via `llama.cpp` (no key required — see [providers docs][docs-providers])\n\n### Installation\n\nFor full setup instructions, see the [Getting Started guide][docs-getting-started].\n\n```sh\n# With pipx (recommended, requires Python 3.10+)\npipx install gptme\n\n# With uv\nuv tool install gptme\n\n# With optional extras\npipx install 'gptme[browser]'  # Playwright for web browsing\npipx install 'gptme[all]'      # Everything\n\n# Latest from git with all extras\nuv tool install 'git+https://github.com/gptme/gptme.git[all]'\n```\n\n### Quick Start\n\n```sh\ngptme\n```\n\nYou'll be greeted with a prompt. Type your request and gptme will respond, using tools as needed.\n\n### Example Commands\n\n```sh\n# Create a particle effect visualization\ngptme 'write an impressive and colorful particle effect using three.js to particles.html'\n\n# Generate visual art\ngptme 'render mandelbrot set to mandelbrot.png'\n\n# Get configuration suggestions\ngptme 'suggest improvements to my vimrc'\n\n# Process media files\ngptme 'convert to h265 and adjust the volume' video.mp4\n\n# Code assistance from git diffs\ngit diff | gptme 'complete the TODOs in this diff'\n\n# Fix failing tests\nmake test | gptme 'fix the failing tests'\n\n# Auto-approve tool confirmations (user can still watch and interrupt)\ngptme -y 'run the test suite and fix any failing tests'\n\n# Fully non-interactive/autonomous mode (no user interaction possible, safe for scripts/CI)\ngptme -n 'run the test suite and fix any failing tests'\n```\n\nFor more, see the [Getting Started][docs-getting-started] guide and the [Examples][docs-examples] in the [documentation][docs].\n\n### ⚙️ Configuration\n\nCreate `~/.config/gptme/config.toml`:\n\n```toml\n[user]\nname = \"User\"\nabout = \"I am a curious human programmer.\"\nresponse_preference = \"Don't explain basic concepts\"\n\n[prompt]\n# Additional files to always include as context\n# files = [\"~/notes/llm-tips.md\"]\n\n[env]\n# Set your default model\n# MODEL = \"anthropic/claude-sonnet-4-20250514\"\n# MODEL = \"openai/gpt-4o\"\n```\n\nFor all options, see the [configuration docs][docs-config].\n\n## 🛠 Usage\n\n```sh\n$ gptme --help\nUsage: gptme [OPTIONS] [PROMPTS]...\n\n  gptme is a chat-CLI for LLMs, empowering them with tools to run shell\n  commands, execute code, read and manipulate files, and more.\n\n  If PROMPTS are provided, a new conversation will be started with it. PROMPTS\n  can be chained with the '-' separator.\n\n  The interface provides user commands that can be used to interact with the\n  system.\n\n  Available commands:\n    /undo         Undo the last action\n    /log          Show the conversation log\n    /edit         Edit the conversation in your editor\n    /rename       Rename the conversation\n    /fork         Create a copy of the conversation\n    /summarize    Summarize the conversation\n    /replay       Replay tool operations\n    /export       Export conversation as HTML\n    /model        Show or switch the current model\n    /models       List available models\n    /tokens       Show token usage and costs\n    /context      Show context token breakdown\n    /tools        Show available tools\n    /commit       Ask assistant to git commit\n    /compact      Compact the conversation\n    /impersonate  Impersonate the assistant\n    /restart      Restart gptme process\n    /setup        Setup gptme\n    /help         Show this help message\n    /exit         Exit the program\n\n  See docs for all commands: https://gptme.org/docs/commands.html\n\n  Keyboard shortcuts:\n    Ctrl+X Ctrl+E  Edit prompt in your editor\n    Ctrl+J         Insert a new line without executing the prompt\n\nOptions:\n  --name TEXT            Name of conversation. Defaults to generating a random\n                         name.\n  -m, --model TEXT       Model to use, e.g. openai/gpt-5, anthropic/claude-\n                         sonnet-4-20250514. If only provider given then a\n                         default is used.\n  -w, --workspace TEXT   Path to workspace directory. Pass '@log' to create a\n                         workspace in the log directory.\n  --agent-path TEXT      Path to agent workspace directory.\n  -r, --resume           Load most recent conversation.\n  -y, --no-confirm       Skip all confirmation prompts.\n  -n, --non-interactive  Non-interactive mode. Implies --no-confirm.\n  --system TEXT          System prompt. Options: 'full', 'short', or something\n                         custom.\n  -t, --tools TEXT       Tools to allow as comma-separated list. Available:\n                         append, browser, chats, choice, computer, gh,\n                         ipython, morph, patch, rag, read, save, screenshot,\n                         shell, subagent, tmux, vision.\n  --tool-format TEXT     Tool format to use. Options: markdown, xml, tool\n  --no-stream            Don't stream responses\n  --show-hidden          Show hidden system messages.\n  -v, --verbose          Show verbose output.\n  --version              Show version and configuration information\n  --help                 Show this message and exit.\n```\n\n## 🌍 Ecosystem\n\ngptme is more than a CLI — it's a platform with a growing ecosystem:\n\n| Project | Description |\n|---------|-------------|\n| [gptme-webui] | Modern React web interface, available at [chat.gptme.org](https://chat.gptme.org) |\n| [gptme-contrib] | Community plugins, packages, scripts, and lessons |\n| [gptme-agent-template][agent-template] | Template for building persistent autonomous agents |\n| [gptme-rag] | RAG integration for semantic search over local files |\n| [gptme.vim] | Vim plugin for in-editor gptme integration |\n| [gptme-tauri] | Desktop app (WIP) |\n| [gptme.ai](https://gptme.ai) | Managed cloud service (WIP) |\n\n**Community agents powered by gptme:**\n- [Bob](https://github.com/TimeToBuildBob) — autonomous AI agent, 1700+ sessions, contributes to open source, manages his own tasks\n- [Alice](https://github.com/TimeToLearnAlice) — personal assistant \u0026 agent orchestrator, forked from the same architecture\n\n## 💬 Community\n\n- **[Discord][discord]** — ask questions, share what you've built, discuss features\n- **[GitHub Discussions](https://github.com/gptme/gptme/discussions)** — longer-form conversation and ideas\n- **[X/Twitter](https://x.com/gptmeorg)** — updates and announcements\n\nContributions welcome! See the [contributing guide](https://gptme.org/docs/contributing.html).\n\n## 📊 Stats\n\n### ⭐ Stargazers over time\n\n[![Stargazers over time](https://starchart.cc/gptme/gptme.svg)](https://starchart.cc/gptme/gptme)\n\n### 📈 Download Stats\n\n- [PePy][pepy]\n- [PyPiStats][pypistats]\n\n[pepy]: https://pepy.tech/project/gptme\n[pypistats]: https://pypistats.org/packages/gptme\n\n## 🔗 Links\n\n- [Website][website]\n- [Documentation][docs]\n- [GitHub][github]\n- [Discord][discord]\n\n\u003c!-- links --\u003e\n\n[website]: https://gptme.org/\n[discord]: https://discord.gg/NMaCmmkxWv\n[github]: https://github.com/gptme/gptme\n[gptme.vim]: https://github.com/gptme/gptme.vim\n[gptme-webui]: https://github.com/gptme/gptme-webui\n[gptme-rag]: https://github.com/gptme/gptme-rag\n[gptme-contrib]: https://github.com/gptme/gptme-contrib\n[gptme-tauri]: https://github.com/gptme/gptme-tauri\n[agent-template]: https://github.com/gptme/gptme-agent-template\n[bob]: https://github.com/TimeToBuildBob\n[docs]: https://gptme.org/docs/\n[docs-getting-started]: https://gptme.org/docs/getting-started.html\n[docs-examples]: https://gptme.org/docs/examples.html\n[docs-demos]: https://gptme.org/docs/demos.html\n[docs-providers]: https://gptme.org/docs/providers.html\n[docs-tools]: https://gptme.org/docs/tools.html\n[docs-tools-python]: https://gptme.org/docs/tools.html#python\n[docs-tools-shell]: https://gptme.org/docs/tools.html#shell\n[docs-tools-patch]: https://gptme.org/docs/tools.html#patch\n[docs-tools-browser]: https://gptme.org/docs/tools.html#browser\n[docs-tools-computer]: https://gptme.org/docs/tools.html#computer\n[docs-lessons]: https://gptme.org/docs/lessons.html\n[docs-skills]: https://gptme.org/docs/skills.html\n[docs-bot]: https://gptme.org/docs/bot.html\n[docs-server]: https://gptme.org/docs/server.html\n[docs-evals]: https://gptme.org/docs/evals.html\n[docs-config]: https://gptme.org/docs/config.html\n[docs-arewetiny]: https://gptme.org/docs/arewetiny.html\n[docs-plugins]: https://gptme.org/docs/plugins.html\n[docs-hooks]: https://gptme.org/docs/hooks.html\n[docs-commands]: https://gptme.org/docs/commands.html\n[docs-mcp]: https://gptme.org/docs/mcp.html\n[docs-acp]: https://gptme.org/docs/acp.html\n[anthropic-computer-use]: https://www.anthropic.com/news/3-5-models-and-computer-use\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgptme%2Fgptme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgptme%2Fgptme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgptme%2Fgptme/lists"}