====== gptme ======

**gptme** is a free, open-source AI agent that runs in your terminal, acting as a personal coding copilot with local tools for executing shell commands, Python code, file editing, web browsing, and vision processing. It supports multiple LLM providers and features self-correcting behavior with an extensible plugin architecture.(([[https://gptme.org|Official Website]]))(([[https://gptme.org/docs|Documentation]]))

{{tag>ai_agent cli coding terminal local_tools open_source}}

| **Repository** | [[https://github.com/gptme/gptme]] |
| **Website** | [[https://gptme.org]] |
| **Language** | Python |
| **License** | MIT |
| **Creator** | Erik Bjare (ErikBjare) |

===== Overview =====

gptme brings AI agent capabilities directly into your terminal with zero cloud dependency for execution. The agent can write code, run shell commands, edit files, browse the web, and analyze images -- all locally on your machine. It feeds output back to the AI for iterative self-correction, enabling autonomous task completion from a single prompt. A web UI and server mode extend its capabilities beyond the terminal.

===== Key Features =====

  * **Shell Execution** -- Runs Bash commands directly in the terminal (git, npm, builds, deployments)
  * **Python/IPython** -- Code execution and REPL integration for data analysis and scripting
  * **File Editing** -- Reads, writes, and edits local files autonomously
  * **Web Browsing** -- Integrated search and browse tools for research and RAG
  * **Vision** -- Multimodal image analysis capabilities
  * **Self-Correcting** -- Feeds output back to AI for iterative refinement
  * **Computer Use** -- Broad local automation for workflow orchestration
  * **Extensible Plugins** -- Add custom tools via gptme-contrib; templates for building agents
  * **RAG Support** -- Retrieval-augmented generation via gptme-rag

===== Architecture =====

gptme is built with a modular architecture consisting of several interconnected components:

  * **gptme CLI** -- Primary terminal interface for interactive conversations
  * **gptme-server** -- Backend service for persistent sessions and web access
  * **gptme-webui** -- React-based browser UI (Vite, TypeScript, shadcn-ui, Tailwind)
  * **gptme-agent-template** -- Starter kit for building custom agents
  * **gptme-contrib** -- Community plugins (Bluesky, Discord, Twitter integrations)
  * **gptme-rag** -- Retrieval-augmented generation module

<mermaid>
graph TD
    A[User] --> B{Interface}
    B --> C[gptme CLI]
    B --> D[gptme-webui]
    D --> E[gptme-server]
    C --> F[Agent Core]
    E --> F
    F --> G[Tool Ecosystem]
    G --> H[Shell / Bash]
    G --> I[Python / IPython]
    G --> J[File Editor]
    G --> K[Web Browser]
    G --> L[Vision]
    G --> M[Computer Use]
    F --> N{LLM Provider}
    N --> O[OpenAI]
    N --> P[Anthropic]
    N --> Q[OpenRouter]
    F --> R[gptme-rag]
    F --> S[gptme-contrib Plugins]
</mermaid>

===== Supported LLMs =====

gptme integrates with multiple LLM providers, selectable at startup:

  * **OpenAI** -- GPT-4, GPT-4o, and newer models
  * **Anthropic** -- Claude family of models
  * **OpenRouter** -- Aggregator providing access to dozens of models
  * Local models via compatible API endpoints

===== Installation =====

<code bash>
# Clone and install
git clone https://github.com/gptme/gptme(([[https://github.com/gptme/gptme|gptme on GitHub]]))(([[https://github.com/ErikBjare/gptme-webui|gptme Web UI]]))
cd gptme
pip install .

# Or install directly
pip install gptme

# Run the CLI
gptme

# Start the server for web UI
gptme-server

# Web UI (separate repo)
git clone https://github.com/ErikBjare/gptme-webui
cd gptme-webui
npm install
npm run dev
</code>

===== CLI Usage =====

<code bash>
# Start interactive session (prompts for provider and API key on first use)
gptme

# Send a prompt directly
gptme "Build a modern React to-do app"

# The agent will:
# 1. Generate code
# 2. Execute shell commands (npx create-react-app, npm install)
# 3. Edit component files
# 4. Run the dev server
# 5. Self-correct based on output
</code>

The agent uses a generate-execute-feedback loop: each step's output feeds back into the AI for the next iteration, enabling autonomous multi-step task completion.

===== See Also =====

  * [[plandex]] -- AI coding agent with plan/apply workflow
  * [[openai_codex]] -- OpenAI Codex CLI agent
  * [[claude_code]] -- Anthropic Claude Code CLI
  * [[warp_terminal]] -- Warp agentic development environment

===== References =====