Terminal UI to chat with large language models (LLM) using different model backends, and integrations with your favourite editors!
Oatmeal is a terminal UI chat application that speaks with LLMs, complete with slash commands and fancy chat bubbles. It features agnostic backends to allow switching between the powerhouse of ChatGPT, or keeping things private with Ollama. While Oatmeal works great as a stand alone terminal application, it works even better paired with an editor like Neovim!
See it in action with Neovim (click to restart):
Note: This project is still quite new, and LLM's can return unexpected answers the UI isn't prepped for. There's likely a few bugs hidden somewhere.
brew install dustinblackman/tap/oatmeal
curl -s https://apt.dustinblackman.com/KEY.gpg | apt-key add -
curl -s https://apt.dustinblackman.com/dustinblackman.list > /etc/apt/sources.list.d/dustinblackman.list
sudo apt-get update
sudo apt-get install oatmeal
dnf config-manager --add-repo https://yum.dustinblackman.com/config.repo
dnf install oatmeal
nix-env -f '<nixpkgs>' -iA nur.repos.dustinblackman.oatmeal
yay -S oatmeal-bin
Chocolatey
choco install oatmeal --version=0.9.2
Scoop
scoop bucket add dustinblackman https://github.com/dustinblackman/scoop-bucket.git
scoop install oatmeal
cargo install oatmeal --locked
Download the pre-compiled binaries and packages from the releases page and copy to the desired location.
git clone https://github.com/dustinblackman/oatmeal.git
cd oatmeal
cargo build --release
mv ./target/release/oatmeal /usr/local/bin/
Oatmeal allows customizing configuration either through command line parameters, or more permanently with environment
variables. By default, Ollama is the selected backend, llama2:latest
as the default model, and the clipboard
integration for an editor.
See oatmeal --help
, /help
in chat, or the output below to get all the details.
Terminal UI to chat with large language models (LLM) using different model backends, and direct integrations with your favourite editors!
Version: 0.9.2
Commit: v0.9.2
Usage: oatmeal [OPTIONS] [COMMAND]
Commands:
chat Start a new chat session
completions Generates shell completions
sessions Manage past chat sessions
help Print this message or the help of the given subcommand(s)
Options:
-b, --backend <backend>
The initial backend hosting a model to connect to. [env: OATMEAL_BACKEND=] [default: ollama] [possible values: ollama, openai]
--backend-health-check-timeout <backend-health-check-timeout>
Time to wait in milliseconds before timing out when doing a healthcheck for a backend [env: OATMEAL_BACKEND_HEALTH_CHECK_TIMEOUT=] [default: 1000]
-m, --model <model>
The initial model on a backend to consume [env: OATMEAL_MODEL=] [default: llama2:latest]
-e, --editor <editor>
The editor to integrate with. [env: OATMEAL_EDITOR=] [default: clipboard] [possible values: neovim, clipboard, none]
-t, --theme <theme>
Sets code syntax highlighting theme. [env: OATMEAL_THEME=] [default: base16-onedark] [possible values: base16-github, base16-monokai, base16-one-light, base16-onedark, base16-seti]
--theme-file <theme-file>
Absolute path to a TextMate tmTheme to use for code syntax highlighting. [env: OATMEAL_THEME_FILE=]
--ollama-url <ollama-url>
Ollama API URL when using the Ollama backend. [env: OATMEAL_OLLAMA_URL=] [default: https://localhost:11434]
--openai-url <openai-url>
OpenAI API URL when using the OpenAI backend. Can be swapped to a compatiable proxy. [env: OATMEAL_OPENAI_URL=] [default: https://api.openai.com]
--openai-token <openai-token>
OpenAI API token when using the OpenAI backend. [env: OATMEAL_OPENAI_TOKEN=]
-h, --help
Print help
-V, --version
Print version
CHAT COMMANDS:
- /modellist (/ml) - Lists all available models from the backend.
- /model (/model) [MODEL_NAME,MODEL_INDEX] - Sets the specified model as the active model. You can pass either the model name, or the index from `/modellist`.
- /append (/a) [CODE_BLOCK_NUMBER?] - Appends code blocks to an editor. See Code Actions for more details.
- /replace (/r) [CODE_BLOCK_NUMBER?] - Replaces selections with code blocks in an editor. See Code Actions for more details.
- /copy (/c) [CODE_BLOCK_NUMBER?] - Copies the entire chat history to your clipboard. When a `CODE_BLOCK_NUMBER` is used, only the specified copy blocks are copied to clipboard. See Code Actions for more details.
- /quit /exit (/q) - Exit Oatmeal.
- /help (/h) - Provides this help menu.
CHAT HOTKEYS:
- Up arrow - Scroll up.
- Down arrow - Scroll down.
- CTRL+U - Page up.
- CTRL+D - Page down.
- CTRL+C - Interrupt waiting for prompt response if in progress, otherwise exit.
- CTRL+R - Resubmit your last message to the backend.
CHAT CODE ACTIONS:
When working with models that provide code, and using an editor integration, Oatmeal has the capabilities to read selected code from an editor, and submit model provided code back in to an editor. Each code block provided by a model is indexed with a (NUMBER) at the beginning of the block to make it easily identifiable.
- /append (/a) [CODE_BLOCK_NUMBER?] will append one-to-many model provided code blocks to the open file in your editor.
- /replace (/r) [CODE_BLOCK_NUMBER?] - will replace selected code in your editor with one-to-many model provided code blocks.
- /copy (/c) [CODE_BLOCK_NUMBER?] - Copies the entire chat history to your clipboard. When a `CODE_BLOCK_NUMBER` is used it will append one-to-many model provided code blocks to your clipboard, no matter the editor integration.
The `CODE_BLOCK_NUMBER` allows you to select several code blocks to send back to your editor at once. The parameter can be set as follows:
- `1` - Selects the first code block
- `1,3,5` - Selects code blocks 1, 3, and 5.
- `2..5`- Selects an inclusive range of code blocks between 2 and 5.
- None - Selects the last provided code block.
The following model backends are supported:
The following editors are currently supported. The clipboard
editor is a special case where any copy or accept commands
are simply copied to your clipboard. This is the default behaviour. Hit any of the links below for more details on how
to use!
- Clipboard (Default)
- None (Disables all editor functionality)
- Neovim
A handful of themes are embedded in the application for code syntax highlighting, defaulting to OneDark. If none suits your needs, Oatmeal supports any Sublime Text/Text Mate
.tmTheme
file, which can be configured through the --theme-file
command line parameter, or the OATMEAL_THEME_FILE
environment variable. base16-textmate has plenty to pick from!
Oatmeal persists all chat sessions with your models, allowing you to go back and review an old conversation, or pick up from where you left off!
Manage past chat sessions
Usage: oatmeal sessions [OPTIONS] [COMMAND]
Commands:
dir Print the sessions cache directory path.
list List all previous sessions with their ids and models.
open Open a previous session by ID. Omit passing any session ID to load an interactive selection.
delete Delete one or all sessions
help Print this message or the help of the given subcommand(s)
Options:
-e, --editor <editor> The editor to integrate with. [env: OATMEAL_EDITOR=] [default: clipboard] [possible values: neovim, clipboard, none]
-t, --theme <theme> Sets code syntax highlighting theme. [env: OATMEAL_THEME=] [default: base16-onedark] [possible values: base16-github, base16-monokai, base16-one-light, base16-onedark, base16-seti]
--theme-file <theme-file> Absolute path to a TextMate tmTheme to use for code syntax highlighting. [env: OATMEAL_THEME_FILE=]
--ollama-url <ollama-url> Ollama API URL when using the Ollama backend. [env: OATMEAL_OLLAMA_URL=] [default: https://localhost:11434]
--openai-url <openai-url> OpenAI API URL when using the OpenAI backend. Can be swapped to a compatiable proxy. [env: OATMEAL_OPENAI_URL=] [default: https://api.openai.com]
--openai-token <openai-token> OpenAI API token when using the OpenAI backend. [env: OATMEAL_OPENAI_TOKEN=]
-h, --help Print help
Grepping through previous sessions isn't something built in to Oatmeal (yet). This bash function can get you there nicely using Ripgrep and FZF.
function oatmeal-sessions() {
(
cd "$(oatmeal sessions dir)"
id=$(rg --color always -n . | fzf --ansi | awk -F ':' '{print $1}' | head -n1 | awk -F '.' '{print $1}')
oatmeal sessions open --id "$id"
)
}
Or something a little more in depth (while hacky) that additionally uses yq and jq.
function oatmeal-sessions() {
(
cd "$(oatmeal sessions dir)"
id=$(
ls | \
(while read f; do echo "$(cat $f)\n---\n"; done;) | \
yq -p=yaml -o=json - 2> /dev/null | \
jq -s . | \
jq -rc '. |= sort_by(.timestamp) | .[] | "\(.id):\(.timestamp):\(.state.backend_model):\(.state.editor_language):\(.state.messages[] | .text | tojson)"' | \
fzf --ansi | \
awk -F ':' '{print $1}' | \
head -n1 | \
awk -F '.' '{print $1}'
)
oatmeal sessions open --id "$id"
)
}
On each Oatmeal release there is a separate download to helps in reporting issues to really drill down in to what the problem is! If you've run in to a problem, I'd really help appreciate solving it.
- Head over to releases and download the DEBUG package for the latest release of Oatmeal.
- Extract the contents of the archive, and
cd
in your terminal inside the archive. - Run your command with the arguments provided in the error message prefixing with
RUST_BACKTRACE=1 ./oatmeal **ARGS-HERE**
- Copy/paste the output and open an issue.
The following will get you set up with all the necessary tooling to work on Oatmeal.
cargo install cargo-run-bin
git clone https://github.com/dustinblackman/oatmeal.git
cd oatmeal
cargo cmd setup
Each backend implements the Backend trait in its own infrastructure file. The trait has documentation on what is expected of each method. You can checkout Ollama as an example.
The following steps should be completed to add a backend:
- Implement trait for new backend.
- Update the BackendName enum with your new Backend name.
- Update the BackendManager to provide your new backend.
- Write tests
Each editor implements the Editor trait in its own infrastructure file. The trait has documentation on what is expected of each method. You can checkout Neovim as an example.
The following steps should be completed to add an editor:
- Implement trait for new editor.
- Update the EditorName enum with your new Editor name.
- Update the EditorManager to provide your new editor.
- Write tests
Syntax highlighting language selection is a tad manual where several languages must be curated and then added to
build.rs
.
- Google to find a
.sublime-syntax
project on Github for your language. bat has many! - Update the
get_syntaxes()
function inbuild.rs
to include the new repo. Make sure to set the URL to a commit locked.tar.gz
file, and to include the license in the files vector. rm -rf .caches && cargo build
- Test to see highlighting works.
I was eating a bowl of oatmeal when I wrote the first commit 🤷. (They don't let me name things at work anymore...)