Published 2024-01-17. Last modified 2025-09-20.
Time to read: 3 minutes.

This page is part of the llm collection.

While exploring the Ollama ecosystem, I found oterm, which is a terminal-based Ollama client.

oterm stores chat sessions locally in a sqlite database. For Linux, the database resides in $HOME/.local/share/oterm/store.db. Some problems can be solved by renaming or deleting this file.

Installation

This is the best way to install oterm:

Shell

$ uv pip install oterm

Other ways are possible.

MCP Support

oterm has support for Anthropic's open-source Model Context Protocol. While Ollama does not yet directly support the protocol, oterm attempts to bridge MCP servers with Ollama.

To add an MCP server to oterm, simply add the server shim to oterm's config.json.

 – oterm documentation

Oterm transforms MCP tools into Ollama tools, supports MCP prompts, MCP sampling, and three types of transport: stdio, Streamable, and Websocket. It also support HTTP bearer authentication.

Help Information

Shell

$ oterm -h

Usage: oterm [OPTIONS]

╭─ Options ───────────────────────────────────────────────────────────╮
│ --version -v                                                        │
│ --upgrade                                                           │
│ --config                                                            │
│ --db                                                                │
│ --data-dir                                                          │
│ --install-completion    Install completion for the current shell.   │
│ --show-completion       Show completion for the current shell,      │
│                         to copy it or customize the installation.   │
│ --help               -h Show this message and exit.                 │
╰─────────────────────────────────────────────────────────────────────╯ 

Running Oterm the First Time

Ollama must already be running before oterm can be used. Unless you set up Ollama to run as a service, you will need to launch it in a different terminal session than oterm.

If you installed oterm as shown above, just type:

Shell

$ oterm

If you instead installed oterm using uvx, as described in certain other tutorials, you must start oterm by typing:

Shell

$ uvx oterm

When oterm starts, it displays a brief splash screen (cute but annoying after the first few times), then a mostly blank screen that looks like this:

The menu at the bottom shows some of the hotkey definitions, unfortunately I found that the menu gets messed up, as you can see with they hotkey for delete chat. I do not know if this is related to Windows Terminal, or a general terminal-related setting.

Next, a quick aside to explain how to configure the oterm hot keys so they do not conflict with Windows Terminal keybindings.

Configuration

The configuration file for oterm is named config.json and is created when oterm is run for the first time. I found it in ~/.local/share/oterm/config.json on my WSL VM.

/home/mslinn/.local/share/oterm/config.json (default)

{"theme": "dark"}

The first thing I did was disable the annoying splash screen:

/home/mslinn/.local/share/oterm/config.json (modified)

{
  "splash-screen": false,
  "theme": "dark"
}

The configuration reported by oterm bears no resemblance to the contents of config.json. 😬

Shell

$ oterm --config
EnvConfig(
│ ENV='development',
│ OLLAMA_HOST='localhost:11434',
│ OLLAMA_URL='http://localhost:11434',
│ OTERM_VERIFY_SSL=True,
│ OTERM_DATA_DIR=PosixPath('/home/mslinn/.local/share/oterm'),
│ OPEN_WEATHER_MAP_API_KEY=''
) 

Hotkeys

The oterm user interface uses some unusual key combinations. This reduces the likelihood of conflicting hotkey definitions with those from the operating system or other applications.

Esc

Cancel any ongoing Ollama inference

CTRL-C

Copy selection to clipboard

CTRL-I

Select an image to include with the next message

CTRL-L

Show logs

CTRL-M

Enable multiline input mode. In multiline mode, press Enter to send the message; pressing SHIFT-Enter to add a newline at the cursor.

CTRL-N

Start a new chat

CTRL-P

Show command palette

CTRL-Q

Quit oterm

CTRL-Backspace

Close the current chat

CTRL-TAB

Move to the next chat in the circular buffer containing all chat histories

CTRL-SHIFT-TAB

Move to the previous chat in the circular buffer containing all chat histories

SHIFT-Enter

Newline

UpArrow and DownArrow

When messages are focused: navigate through messages
When prompt is focused: navigate through prompt history

Unfortunately, Windows Terminal uses CTRL-TAB and CTRL-SHIFT-TAB to activate the next and previous tabs. Instead of modifying the Windows Terminal default hotkeys, I modified the oterm keymap to use ALT-N and ALT-P for navigating between saved chats:

/home/mslinn/.local/share/oterm/config.json (modified)

{
  "keymap": {
    "next.chat": "alt+n",
    "prev.chat": "alt+p"
  },
  "splash-screen": false,
  "theme": "dark"
}

Using oterm

I pressed CTRL-N to start a new chat session and was presented with the following:

The currently installed Ollama models were displayed in a selection box at the top left.

I clicked on the mistral-small3.2:latest model, and clicked the Save button.

The message that I typed into the input widget at the bottom of the screen was:
what is the meaning of life. After clicking on the post button, and waiting for a few minutes, an answer appeared.

In another chat session, using the llava LLM, I queried “What was the color of George Washington's white horse?”, and after a few minutes got a response in Chinese:

I tried the same query again using the samantha-mistral LLM and got the correct reply in English:

The image browser was unusable. It could not change directories or switch to other drives. I wrote up an issue, and a week later it was fixed.

Share to X, Hacker News, LinkedIn.