Home

Awesome

oterm

the text-based terminal client for Ollama.

Table of Contents

Features

Installation

Ollama

Ollama needs to be installed and running in order to use oterm. Please follow the Ollama Installation Guide.

oterm

Using brew for MacOS:

brew tap ggozad/formulas
brew install ggozad/formulas/oterm

Using yay (or any AUR helper) for Arch Linux:

yay -S oterm

Using pip:

pip install oterm

Updating oterm

To update oterm to the latest version, you can use the same method you used for installation:

Using brew for MacOS:

brew upgrade ggozad/formulas/oterm

Using 'yay' (or any AUR helper) for Arch Linux:

yay -Syu oterm

Using pip:

pip install --upgrade oterm

Using

In order to use oterm you will need to have the Ollama server running. By default it expects to find the Ollama API running on http://127.0.0.1:11434. If you are running Ollama inside docker or on a different host/port, use the OLLAMA_HOST environment variable to customize the host/port. Alternatively you can use OLLAMA_URL to specify the full http(s) url. Setting OTERM_VERIFY_SSL to False will disable SSL verification.

OLLAMA_URL=http://host:port

To start oterm simply run:

oterm

Commands

By pressing <kbd>^ Ctrl</kbd>+<kbd>p</kbd> you can access the command palette from where you can perform most of the chat actions. The following commands are available:

Keyboard shortcuts

The following keyboard shortcuts are supported:

In multiline mode, you can press <kbd>Enter</kbd> to send the message, or <kbd>Shift</kbd>+<kbd>Enter</kbd> to add a new line at the cursor.

While Ollama is inferring the next message, you can press <kbd>Esc</kbd> to cancel the inference.

Note that some of the shortcuts may not work in a certain context, for example pressing <kbd></kbd> while the prompt is in multi-line mode.

Tools

Since version 0.6.0 oterm supports integration with tools. Tools are special "functions" that can provide external information to the LLM model that it does not otherwise have access to.

The following tools are currently supported:

The tooling API in Ollama does not currently support streaming. When using tools, you will have to wait for the tools & model to finish before you see the response.

Note that tools integration is experimental and may change in the future. I particularly welcome contributions for new tools, but please bear in mind that any additional requirements in terms of dependencies or paid-for API usage should be kept to a minimum.

Copy / Paste

It is difficult to properly support copy/paste in terminal applications. You can copy blocks to your clipboard as such:

For most terminals there exists a key modifier you can use to click and drag to manually select text. For example:

Customizing models

When creating a new chat, you may not only select the model, but also customize the the system instruction, tools used, as well as the parameters (such as context length, seed, temperature etc) passed to the model. For a list of all supported parameters refer to the Ollama documentation. Checking the JSON output checkbox will force the model to reply in JSON format. All the models you have pulled or created will be available to oterm.

You can also "edit" the chat to change the system prompt, parameters or format. Note, that the model cannot be changed once the chat has started.

Chat session storage

All your chat sessions are stored locally in a sqlite database. You can customize the directory where the database is stored by setting the OTERM_DATA_DIR environment variable.

You can find the location of the database by running oterm --db.

App configuration

The app configuration is stored in a directory specific to your operating system, by default:

If in doubt you can get the directory where config.json can be found by running oterm --data-dir.

You can set the following options in the configuration file:

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

theme can be either dark or light. splash-screen controls whether the splash screen is shown on startup.

Key bindings

We strive to have sane default key bindings, but there will always be cases where your terminal emulator or shell will interfere. You can customize select keybindings by editing the app config config.json file. The following are the defaults:

{
  ...
  "keymap": {
    "next.chat": "ctrl+tab",
    "prev.chat": "ctrl+shift+tab",
    "quit": "ctrl+q",
    "newline": "shift+enter",
  }
}

Screenshots

Splash The splash screen animation that greets users when they start oterm.

Chat A view of the chat interface, showcasing the conversation between the user and the model.

Model selection The model selection screen, allowing users to choose from available models.

Image selection The image selection interface, demonstrating how users can include images in their conversations.

License

This project is licensed under the MIT License.