# oterm: a terminal client for Ollama, OpenAI, Anthropic and pydantic-ai providers

> oterm puts an LLM chat UI inside the terminal, stores conversations in SQLite, and now speaks to any pydantic-ai provider rather than Ollama alone. The 0.24.x line is a rewrite of the provider and MCP layers, which makes the upgrade path the main thing to check before adopting it.

**ggozad/oterm** — the terminal client for LLMs

- Repository: https://github.com/ggozad/oterm
- Stars: 2,444 · Forks: 139
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ggozad-oterm

## The gap oterm fills between a shell prompt and a browser chat tab

Running a local model through Ollama usually means either typing curl commands or opening a web UI that lives in a browser. oterm takes the third option: a Textual-based terminal application that keeps the conversation, the model selection and the prompt inside the terminal window you already have open. The README describes it as "the terminal client for Ollama, OpenAI, Anthropic, and any pydantic-ai-supported provider", so the target user is a developer who works in a terminal, wants to switch between a local Ollama model and a hosted API without changing tools, and does not want a separate desktop app.

The stored-conversation model is the part that distinguishes it from a one-shot CLI wrapper. Chats persist, so you return to a thread rather than re-pasting context. The pyproject.toml lists aiosql and aiosqlite as dependencies, which indicates the persistence layer is SQLite accessed asynchronously rather than a flat file. For someone who uses an LLM for exploratory work across several sessions, that is the practical difference between a toy and a tool.

## How oterm talks to providers, and why 0.24.0 changed the contract

The architecture is layered. Textual renders the interface, pydantic-ai handles the model conversation, and the provider is selected at runtime. The pyproject.toml dependency line is the clearest evidence of the design: pydantic-ai-slim is installed with the openai, anthropic, google, groq, mistral, cohere, bedrock, huggingface, mcp, logfire, duckduckgo and web-fetch extras bundled in. That is a wide surface, and it is why the README can claim OpenAI-compatible endpoints such as vLLM, LM Studio, llama.cpp, OpenRouter and LiteLLM work without dedicated code.

The release notes describe the mechanism for provider discovery plainly: set the matching API key and the provider appears in the new-chat dropdown. There is no separate provider configuration file to write for the hosted services. Ollama remains supported, and the ollama package is pinned as a direct dependency, so the local path is not an afterthought.

The breaking part matters more than the feature list. Before 0.24.0 the project was Ollama-only, and the MCP configuration used a block called mcpServers. That block now follows pydantic-ai's standard schema, which the README says is compatible with Claude Desktop and Cursor. Anyone carrying an older config forward will find it silently ignored rather than rejected, which is the failure mode worth planning for. The README points to docs/mcp for migration notes; the README itself does not document an automatic migration.

## Installing oterm and starting a first conversation

The README gives a single command as the install path, using uvx to run the package without a permanent install. The project also publishes a full install guide on its documentation site, but the README's own example is this:

```bash
uvx oterm
```

Running that should launch the terminal interface. On first start there is no configured provider beyond whatever is reachable locally, so an Ollama daemon on the default port is the path of least resistance. The README does not spell out the default port in the text shown, and neither does the pyproject.toml, so confirm it against the Ollama documentation rather than assuming.

For the spoken-response feature, the README gives a different invocation that pulls in an optional dependency group:

```bash
uvx "oterm[speak]"
```

The README states this extra needs Python 3.11 or newer, and the pyproject.toml confirms the constraint is written as a python_version marker on pydantic-ai-tts. The base install is untouched by this: the README says the capability appears only once the extra is present, so a plain uvx oterm will not show it.

To add a hosted provider, the README's instruction is to set the matching API key. The project depends on python-dotenv, which suggests a .env file is read at startup, though the README excerpt does not give the exact variable names. Check the documentation site for the key names before exporting anything.

## Where oterm gets in the way

The MCP rewrite is the sharpest limitation. A configuration block that worked in 0.23.x is not the block 0.24.0 reads. The README calls this breaking and routes readers to a separate documentation page. If you depend on MCP servers for tool access, an upgrade is a migration project, not a version bump, and the README does not describe a compatibility shim or a fallback to the old schema.

The second constraint is platform support as declared rather than as tested. The classifiers list Android, Windows 10 and 11, macOS and Linux, which is unusually broad for a Textual application, and the presence of textual-image and textualeffects as dependencies means the rendering path assumes a terminal that handles images and effects. Terminals vary widely in that respect. The repository does not publish a compatibility matrix in what it makes available, so a terminal that renders poorly is a real possibility rather than an edge case.

Third, the project classifies itself as "Development Status :: 4 - Beta". Combined with three releases in the two months before the last push, that is an honest signal: the configuration surface is still moving. Teams that need a frozen interface should treat that label as accurate rather than cautious.

Finally, the README excerpt does not document rollback, data export, or what happens to an existing SQLite history when the schema changes. The last push was on 2026-09-02, so the project is current, but currency is not the same as stability.

## oterm against Parllama and the plain Ollama CLI

Parllama is the closest alternative that appears in the search data around this project, and the difference is architectural rather than cosmetic. Parllama is a Textual application built around Ollama model management: browsing, pulling and organising local models is the centre of the interface. oterm treats model management as Ollama's job and puts the conversation at the centre, then adds hosted providers through pydantic-ai. If your work is mostly local models and you want a visual way to manage them, Parllama's approach fits better. If your work is mostly conversation and you move between a local model and a hosted one, oterm's provider layer is the reason to pick it.

The Ollama CLI itself is the other comparison. It is a thin client: prompt in, response out, no persistent thread and no provider abstraction. oterm's SQLite-backed history and its dropdown of providers are the two things the CLI does not attempt. The trade-off runs the other way for scripting, where a thin CLI is easier to pipe and oterm's interactive interface is not designed for it.

## Maintenance, licensing and what an upgrade actually costs

The repository is not archived and the last push was on 2026-09-02, two weeks before this writing, with 0.24.0 released the same day. The two prior releases, 0.23.0 and 0.23.1, landed on 2026-07-31 and 2026-08-06. That cadence, roughly a release a month, tells you the maintenance cost is not zero: there is an active version stream to track, and the 0.24.0 notes show that stream can carry breaking changes.

The dependency pins reinforce this. Versions are exact rather than ranged for most packages, including textual at 8.2.8 and pydantic-ai-slim at 2.37.0. Exact pins make installs reproducible, but they also mean upgrading oterm usually means upgrading a coordinated set of pinned libraries at once. The one deliberate exception is text-image, where a comment in pyproject.toml explains that 0.13.x requires Python 3.12 while oterm supports 3.10 and above. That is a maintenance decision made in the open, and it is the kind of detail that predicts how the project handles future dependency conflicts.

On licensing: oterm is MIT, stated in both the README and the pyproject.toml license field. MIT is permissive and imposes no copyleft obligation on your own code. That says nothing about the licences of the providers or optional components you connect it to. The speak extra depends on pydantic-ai-tts, and the README names piper as the voice engine; those carry their own terms, and the README does not summarise them. Check them separately if you intend to ship anything built on top.

## Conclusion

Adopt oterm if you already run Ollama locally or hold API keys for a pydantic-ai provider and want a keyboard-driven, self-contained chat client without a browser tab. Skip it if you need a stable configuration surface across versions, because the 0.24.0 release changed the provider model and the mcpServers schema in ways the README explicitly labels breaking, or if you want a GUI with visual model management. Before committing, verify three things: that the models you intend to use are reachable from the provider you configure, that an existing mcpServers block has been migrated to the pydantic-ai schema described in docs/mcp, and that the Python interpreter is 3.11 or newer if you want the speak extra. The chat history lives in a local SQLite file, so the migration question is the one that decides whether an upgrade is routine or disruptive.

## FAQ

### How do I install oterm?

The README gives uvx oterm as the install-and-run command, and points to the project documentation site for full install methods and configuration. For the spoken-response feature the README gives a separate command, uvx "oterm[speak]", which requires Python 3.11 or newer.

### Does oterm work only with Ollama?

No. The README states that oterm drives any pydantic-ai-supported provider, including OpenAI, Anthropic, Google, Groq, Mistral, Cohere, AWS Bedrock, DeepSeek, Cerebras, Grok, Hugging Face, OpenAI-compatible endpoints and Ollama. You set the matching API key and the provider appears in the new-chat dropdown.

### What broke in oterm 0.24.0?

The release notes list two breaking changes: the project moved from Ollama-only to multi-provider through pydantic-ai, and the mcpServers config block now follows pydantic-ai's standard schema instead of the previous format. The README directs readers to docs/mcp for the migration notes.

### Which Python versions does oterm support?

The pyproject.toml sets requires-python to >=3.10 and classifies Python 3.10 through 3.14. The speak extra is the exception: the README states it needs Python 3.11 or newer, and the optional dependency is marked with a python_version >= '3.11' condition.

## Sources

- [ggozad/oterm on GitHub](https://github.com/ggozad/oterm)
- [Issues](https://github.com/ggozad/oterm/issues)
- [License: MIT](https://github.com/ggozad/oterm/blob/main/LICENSE)
- [README](https://github.com/ggozad/oterm/blob/main/README.md)
- [Releases](https://github.com/ggozad/oterm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ggozad-oterm