oterm CLI
oterm is a terminal chat for Ollama, OpenAI, Anthropic and other providers: SQLite-stored sessions, MCP servers, built-in and custom tools
- 2,446 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The built-in `shell` tool runs shell commands at the model's request with no directory limit
- The `filesystem` capability reads and writes files in the launch directory, and MCP servers start as separate processes
- Hosted-provider keys come from the environment and chat text goes to the chosen provider, while web search and URL fetching reach the network
Install
Manual install
uvx otermRuns oterm without installing it. uvx oterm@latest picks up a newer version.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The built-in `shell` tool runs shell commands at the model's request with no directory limit
- The `filesystem` capability reads and writes files in the launch directory, and MCP servers start as separate processes
- Hosted-provider keys come from the environment and chat text goes to the chosen provider, while web search and URL fetching reach the network
This is third-party code. Review the repository files before installing.
What it does
oterm starts with the `oterm` command (or `uvx oterm`) and opens a terminal interface for chatting with language models. It finds providers from the environment: a running Ollama at 127.0.0.1:11434 shows up with no setup, and for hosted providers it is enough to set a key in an environment variable. The list covers Ollama, OpenAI, Anthropic, Google, Groq, Mistral, Cohere, AWS Bedrock, DeepSeek, Cerebras, Grok, Hugging Face and any OpenAI-compatible endpoint such as vLLM, LM Studio, llama.cpp, OpenRouter and LiteLLM. Each chat is stored in SQLite together with its system prompt and parameters, and several chats can sit in tabs. Tools can be attached to the model. Built-in ones are `think`, `date_time`, `shell` and `generate_image` (images through an Ollama image model). A custom tool is a Python function registered in the `oterm.tools` entry-point group, and oterm picks it up at startup. Any MCP server goes under the `mcpServers` key of `config.json`, with the same schema as Claude Desktop and Cursor. The model sees each tool as `{server}_{tool}`, and you enable tools per chat. Beyond tools there are pydantic-ai capabilities: `web_search`, `web_fetch`, `memory` (a shared notebook in `memory.db`), `filesystem` (read, write and search files only under the launch directory), `summarize` and `speak`. When a conversation fills 80% of the context window, `summarize` replaces older messages with a summary written by the chat's own model and keeps the latest 40% of the window as it is. Commands run from the Ctrl+p palette: rename and export a chat as Markdown, regenerate the last answer, prompt history, logs. Images are added to a message with Ctrl+i.
Who it is for. For developers and local-model enthusiasts who want a fast terminal chat across several providers and a way to try MCP servers without an editor.
Good fit when
- Ollama, vLLM or LM Studio runs on the machine and you want a terminal chat without a browser or a separate web interface
- You want to see how a specific model calls an MCP server's tools without wiring the server into an editor or an agent
- You switch between a local model and a hosted one, such as OpenRouter or Anthropic, and want all chats stored in one place with their system prompts and parameters
- You need your own tool for the model: a Python function registered through `oterm.tools` plugs in without changes to oterm
- Long conversations hit the context window and older messages should be folded into a summary automatically
Not a fit when
- You need an agent that edits a repository, runs tests and commits: oterm stays a chat, and it reads and writes files only under the launch directory
- Your MCP server is reachable only over `ws://` or `wss://`: those transports are unsupported, use HTTP or stdio
- You need MCP prompts and templates: the Use MCP prompt command was removed and only tools are supported
- You need a graphical interface with a mouse: oterm is built for the terminal and key bindings
Example request
Install oterm, connect my local Ollama and add a git MCP server to config.json so the model can browse commit historyLimitations
- The MCP integration was rewritten on pydantic-ai's MCP support. The old `auth` field of type bearer is no longer read, and such an entry is dropped silently until the server starts answering 401. A token now goes in an `Authorization` header.
- Stdio server processes do not inherit the environment apart from `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM` and `USER` on Linux and macOS. Declare every other variable under `env`. A server name may contain only letters, digits, underscores and hyphens, or the server will not load.
- Not every model can call tools, and small ones cope worse: if calls fail, reduce the number of tools in the chat or pick a larger model.
- The `speak` capability needs an extra package with `piper-tts` under GPL-3.0 and reads responses in a single GLaDOS voice that cannot be changed.
- The Arch, NixOS and FreeBSD packages are community-maintained and may lag behind the release. MIT license.
How to disable. Quit oterm with Ctrl+q. A `uvx` run leaves nothing installed, for `pip` run `pip uninstall oterm`, for Homebrew `brew uninstall oterm`. Chats and settings live in the data directory, `oterm --data-dir` prints its path, and you can delete that directory by hand.
FAQ
Which model providers does oterm support?
Ollama, OpenAI, Anthropic, Google, Groq, Mistral, Cohere, AWS Bedrock, DeepSeek, Cerebras, Grok, Hugging Face and any OpenAI-format endpoint, local (vLLM, LM Studio, llama.cpp) or hosted (OpenRouter, LiteLLM). Ollama at 127.0.0.1:11434 is picked up on its own, others need a key in an environment variable, and your own endpoints go in the `openaiCompatible` block.
How do I add an MCP server to oterm?
Put it under the `mcpServers` key of `config.json` in the Claude Desktop and Cursor format: `command`, `args` and `env` for a local server, `url` for a remote one. An address ending in `/sse` is treated as SSE and others as streamable HTTP. A token goes in the `headers` field as `Authorization`. You enable the server in the chat's tool selector.
How does the filesystem capability differ from the shell tool?
`filesystem` reads, writes and searches files only under the directory oterm was started from and rejects paths outside it. `.git`, `.env`, keys and secrets are read-only. `shell` runs shell commands and hands the output to the model, has no directory limit, and the author advises caution.
Where does oterm keep chats and model memory?
In the data directory: `~/.local/share/oterm` on Linux, `~/Library/Application Support/oterm` on macOS, `AppData/Roaming/oterm` on Windows. Chats sit in SQLite together with the system prompt and parameters, and the model's shared memory in `memory.db`. `OTERM_DATA_DIR` moves the directory and `oterm --data-dir` prints the current path.
How do I write my own tool for the model?
Write a Python function: its name, docstring and type annotations become the tool definition for the model. Register it in `pyproject.toml` under the `oterm.tools` group, install the package into the same environment as oterm and select the tool when creating a chat. The `oracle` example is in the repository's `docs/oracle` folder.
Discussion
No questions or reviews yet.
Related
CLI toolsOllama runs open models on your own machine and serves them to agents through a local API compatible with OpenAI and Anthropic.
A terminal MCP client for local Ollama models: MCP tools, prompts and resources, an agent mode and model switching
A CLI and Python library for OpenAI, Claude, Gemini, local and other models: prompts, chats, tools, embeddings and a SQLite log
A personal AI agent for the terminal with shell, Python, web and local models, one of the earliest agent CLIs
An MCP server that sends one prompt to several OpenAI, Anthropic, Gemini, Groq, DeepSeek and Ollama models at once and can draw a decision from them
A local-first AI agent running on your own machine via llama.cpp that drives a browser, edits files, runs approved commands and remembers context across session
README in short
The repository's front page is short: one line saying it is a terminal client for Ollama, OpenAI, Anthropic and pydantic-ai providers, a splash animation, the `uvx oterm` install command, links to the documentation and changelog, and the MIT license. Details sit in the docs folder: features, install methods, configuration, MCP, tools, commands and key bindings, model parameters and a RAG example. The repository also holds an example custom tool, tests for the app and the agent, and a changelog.