This is an old revision of the document!

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.

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

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]

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

# Clone and install
git clone https://github.com/gptme/gptme
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

CLI Usage

# 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

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.

AI Agent Knowledge Base

Sidebar

Table of Contents

gptme

Overview

Key Features

Architecture

Supported LLMs

Installation

CLI Usage

References

See Also

AI Agent Knowledge Base

User Tools

Site Tools

Sidebar

Table of Contents

gptme

Overview

Key Features

Architecture

Supported LLMs

Installation

CLI Usage

References

See Also

Page Tools