gptme Terminal Agent
A local terminal agent for coding, file work, web tasks, and automation across model providers.
Per-dimension scores and reasoning
Evidence shows: README explicitly states the tool runs with user permissions, interactive mode requires user confirmation, non-interactive mode is for trusted environments; SECURITY.md provides security model and vulnerability reporting process; pyproject.toml has version constraints and notes pypdf CVE fix; /undo command and auto-snapshot hooks exist; security contact email provided. Deductions: no detailed least-privilege configuration, user confirmation implementation not shown in source, data flow transparency only via documentation, sensitive data handling not detailed, dependency security only partially pinned, external effects (e.g., network) not detailed, rollback only via /undo and snapshots, source attribution only via author info.
Evidence shows: README and pyproject.toml descriptions are consistent, version numbers match; dependency list is complete with optional groups; test files and CI config exist, but no specific failure message examples. Deductions: self-consistency based only on docs and config, no tests run; dependency availability not verified; failure messages not evident in source.
Evidence shows: README clearly targets developers, scenarios include coding, data analysis, research; tool list is clear with shell, python, browser; /tools command to view tool status; supports multiple platforms and Python versions. Deductions: capability boundaries not explicitly stated (e.g., permission limits), trigger precision (e.g., tool call conditions) not detailed, environment fit (e.g., OS differences) not deep.
Evidence shows: README structure is clear with TOC, install, usage, config; install instructions detailed with pipx, uv; naming stable, version clear; example commands and FAQ links; known limitations not explicitly listed; MIT license file present; changelog and timeline links; maintenance responsibility by author. Deductions: information architecture good but no full doc index; install notes not cover all platforms; naming stability not verified; examples and FAQ not in repo; known limitations not explicit; versioning has changelog but not in repo; maintenance responsibility only via author info.
Evidence shows: README provides multiple use cases and example commands, output format has JSONL option; high marginal value with rich features; cost-benefit not explicit but open-source free. Deductions: output usability not actually tested; marginal value based on feature list, not quantified; cost-benefit no specific data.
Evidence shows: README claims have links (e.g., docs, examples); test files and CI config exist for cross-validation; facts and inferences not explicitly separated. Deductions: claim traceability only via links, not verified; cross-source corroboration not actually performed; facts and inferences not clearly labeled.
- The tool runs with user permissions and can execute arbitrary commands; use only in trusted environments and be cautious with non-interactive mode.
- Dependency versions are partially pinned but no lock file is provided; consider using a lock file for reproducibility.
- Security model relies on user confirmation, but implementation is not shown; review code to verify confirmation mechanism effectiveness.
What does this agent do, and when should you use it?
gptme is a personal AI agent that runs in a terminal, with interactive sessions, non-interactive automation, and JSON-formatted output. It uses tools including shell, ipython, read, save, patch, browser, vision, tmux, and subagent to work in a local environment. The project supports Anthropic, OpenAI, Google, xAI, DeepSeek, OpenRouter, and local models served through llama.cpp. It also includes a gptme-server REST API, a bundled gptme-webui, and an ACP route for use from Zed and JetBrains IDEs. For persistent operation, gptme-agent-template supplies a scaffold with a durable workspace, task management, and scheduled or event-driven run loops.
A user starts gptme [PROMPTS]... interactively or passes a task on the command line; the model then invokes enabled tools as needed. shell runs terminal commands, ipython runs Python, read reads files and directories, save, append, patch, and morph create or update files, browser searches and navigates through Playwright, and vision and screenshot process images or desktop captures. The documented tool set also includes gh, tmux, rag, computer, subagent, and chats. Tool results are fed back to the assistant so it can continue and self-correct. For automation, gptme --non-interactive --output-format json emits one JSON object per line, while gptme-server exposes a REST API.
- A developer working in a local repository can ask gptme to write code, run tests, inspect failures, and apply incremental edits with shell, ipython, and patch.
- An engineering team running tasks through SSH, tmux, headless servers, or CI can use -n or --non-interactive for unattended execution.
- A researcher or developer who needs web findings alongside local files can combine the Playwright-backed browser tool with rag.
- A user wanting to switch among hosted providers and locally served models can configure a provider credential or a llama.cpp endpoint.
- A developer using Zed or JetBrains can install gptme[acp] to use gptme as a coding agent from the editor.
- A team building a continuously operating agent can start from gptme-agent-template for its persistent workspace and run-loop structure.
What are this agent's strengths and limitations?
- Its terminal toolset spans command execution, Python, incremental file editing, Playwright browsing, image handling, tmux, and desktop interaction.
- It documents provider choice across several hosted services, OpenRouter, and local llama.cpp models rather than a single-model path.
- It offers an interactive CLI, non-interactive JSON output, a REST API, a Web UI, and ACP-based editor access.
- The separate gptme-agent-template provides concrete building blocks for persistent agents, including tasks, knowledge, and coordination.
- It requires Python 3.10+ and, except for the local llama.cpp route, credentials for at least one LLM provider.
- Enabled shell, file-editing, browser, and computer tools can act directly in the local environment; -y and -n skip confirmation prompts.
- Web browsing depends on the optional browser installation, which adds Playwright.
- The persistent-agent workflow depends on the separate gptme-agent-template rather than the base gptme installation alone.
How do you install or deploy this agent?
Python 3.10+ is required. Recommended installation: pipx install gptme; uv tool install gptme is also documented. For web browsing, install pipx install 'gptme[browser]'; for all optional components, install pipx install 'gptme[all]'. Configure credentials for at least one provider, such as ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY, or connect to a local llama.cpp server, which needs no API key.
How do you use this agent?
Start an interactive session with: gptme. To pass a task directly, use: gptme 'suggest improvements to my vimrc'. For test automation with confirmation skipping, use: gptme -y 'run the test suite and fix any failing tests'. For fully non-interactive execution, use: gptme -n 'run the test suite and fix any failing tests'. For machine-readable output, run: gptme --non-interactive --output-format json 'summarize the current git diff'. For a local model, start llama-server, set OPENAI_BASE_URL=http://localhost:8080/v1, then run gptme -m local/<model-name>.
How does this agent compare with similar options?
The project presents itself as an alternative to Claude Code, Codex, Cursor, and Warp. Its stated distinctions include running in terminal environments, multi-provider and local llama.cpp support, built-in MCP support, web browsing, self-hosting, and persistent autonomous-agent scaffolding.