• Stars
    star
    483
  • Rank 91,050 (Top 2 %)
  • Language
    Rust
  • License
    MIT License
  • Created about 1 year ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Terminal UI to chat with large language models (LLM) using different model backends, and integrations with your favourite editors!

Oatmeal

oatmeal

Build Status Release Coverage Status

Terminal UI to chat with large language models (LLM) using different model backends, and integrations with your favourite editors!

Overview

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):

oatmeal-demo

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.

Install

MacOS

brew install dustinblackman/tap/oatmeal

Debian / Ubuntu

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

Fedora / CentOS

dnf config-manager --add-repo https://yum.dustinblackman.com/config.repo
dnf install oatmeal

Nix

nix-env -f '<nixpkgs>' -iA nur.repos.dustinblackman.oatmeal

Arch Linux

yay -S oatmeal-bin

Alpine Linux

arch=$(uname -a | grep -q aarch64 && echo 'arm64' || echo 'amd64')
curl -L -o oatmeal.apk "https://github.com/dustinblackman/oatmeal/releases/download/v0.12.4/oatmeal_0.12.4_linux_${arch}.apk"
apk add --allow-untrusted ./oatmeal.apk

Windows

Chocolatey

choco install oatmeal --version=0.12.4

Scoop

scoop bucket add dustinblackman https://github.com/dustinblackman/scoop-bucket.git
scoop install oatmeal

Winget

winget install -e --id dustinblackman.oatmeal

Cargo

cargo install oatmeal --locked

Docker

docker run --rm -it ghcr.io/dustinblackman/oatmeal:latest

Manual

Download the pre-compiled binaries and packages from the releases page and copy to the desired location.

Source

git clone https://github.com/dustinblackman/oatmeal.git
cd oatmeal
cargo build --release
mv ./target/release/oatmeal /usr/local/bin/

Usage

The following shows the availabe options to start a chat session. By default when running oatmeal, Ollama is the selected backend, 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.12.4
Commit: v0.12.4

Usage: oatmeal [OPTIONS] [COMMAND]

Commands:
  chat         Start a new chat session.
  completions  Generates shell completions.
  config       Configuration file options.
  manpages     Generates manpages and outputs to stdout.
  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. [default: ollama] [env: OATMEAL_BACKEND=] [possible values: langchain, 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. [default: 1000] [env: OATMEAL_BACKEND_HEALTH_CHECK_TIMEOUT=]
  -m, --model <model>
          The initial model on a backend to consume. Defaults to the first model available from the backend if not set. [env: OATMEAL_MODEL=]
  -c, --config-file <config-file>
          Path to configuration file [default: ~/.config/oatmeal/config.toml] [env: OATMEAL_CONFIG_FILE=]
  -e, --editor <editor>
          The editor to integrate with. [default: clipboard] [env: OATMEAL_EDITOR=] [possible values: neovim, clipboard, none]
  -t, --theme <theme>
          Sets code syntax highlighting theme. [default: base16-onedark] [env: OATMEAL_THEME=] [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=]
      --lang-chain-url <lang-chain-url>
          LangChain Serve API URL when using the LangChain backend. [default: http://localhost:8000] [env: OATMEAL_LANGCHAIN_URL=]
      --ollama-url <ollama-url>
          Ollama API URL when using the Ollama backend. [default: http://localhost:11434] [env: OATMEAL_OLLAMA_URL=]
      --open-ai-url <open-ai-url>
          OpenAI API URL when using the OpenAI backend. Can be swapped to a compatible proxy. [default: https://api.openai.com] [env: OATMEAL_OPENAI_URL=]
      --open-ai-token <open-ai-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.

Configuration

On top of being configurable with command flags and environment variables, Oatmeal is also manageable with a configuration file such as this example. You can run oatmeal config create to initialize for the first time.

Configuration file options.

Usage: oatmeal config [OPTIONS] [COMMAND]

Commands:
  create   Saves the default config file to the configuration file path. This command will fail if the file exists already.
  default  Outputs the default configuration file to stdout.
  path     Returns the default path for the configuration file.
  help     Print this message or the help of the given subcommand(s)

Backends

The following model backends are supported:

Editors

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

Themes

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 with the theme-file configuration option. base16-textmate has plenty to pick from!

Sessions

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)

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"
    )
}

Contributing

Report an issue

On each Oatmeal release there is a separate download to help 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.

  1. Head over to releases and download the DEBUG package for the latest release of Oatmeal.
  2. Extract the contents of the archive, and cd in your terminal inside the archive.
  3. Run your command with the arguments provided in the error message prefixing with RUST_BACKTRACE=1 ./oatmeal **ARGS-HERE**
  4. Copy/paste the output and open an issue. Include any screenshots you believe will be helpful!

Development

Setup

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

Adding a backend

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:

  1. Implement trait for new backend.
  2. Update the BackendName enum with your new Backend name.
  3. Update the BackendManager to provide your new backend.
  4. Write tests

Adding an editor

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:

  1. Implement trait for new editor.
  2. Update the EditorName enum with your new Editor name.
  3. Update the EditorManager to provide your new editor.
  4. Write tests

Adding syntax highlighting for a language

Syntax highlighting language selection is a tad manual where several languages must be curated and then added to assets.toml.

  1. Google to find a .sublime-syntax project on Github for your language. bat has many!
  2. Update assets.toml to include the new repo. Make sure to include the license in the files array. You can leave nix-hash as an empty string, and it'll be updated by a maintainer later. Or if you have docker installed, you can run cargo xtask hash-assets.
  3. rm -rf .caches && cargo build
  4. Test to see highlighting works.

FAQ

Why Oatmeal?

I was eating a bowl of oatmeal when I wrote the first commit 🤷. (They don't let me name things at work anymore...)

License

MIT

More Repositories

1

Championify

Import recent item sets from popular aggregators like Champion.gg in to League of Legends to use within game! No hassle.
HTML
889
star
2

cargo-run-bin

Build, cache, and run CLI tools scoped in Cargo.toml rather than installing globally. Stop the version drifts across your team, keep it all in sync within your project!
Rust
173
star
3

streamroller

Self hosted simulcasting to Twitch, Youtube, and Facebook made easy.
Go
157
star
4

oatmeal.nvim

Terminal UI to chat with large language models (LLM) using different model backends, and with a plugin for Neovim!
Lua
77
star
5

phantomized

All dynamic PhantomJS ELFs in one simple tar
JavaScript
69
star
6

speakerbot

A simple Discord music bot written in Go
Go
51
star
7

gomodrun

The forgotten go tool that executes and caches binaries included in go.mod files.
Go
34
star
8

languagetool-code-comments

languagetool-code-comments integrates the LanguageTool API to parse, spell check, and correct the grammar of your code comments!
Rust
31
star
9

tcon

A slightly lazy shell script to run parallel commands with tmux panes through a FIFO queue.
Shell
30
star
10

collectd-docker-plugin

A collectd plugin that taps in the Docker Stats API
Go
25
star
11

s

A command line utility for posting status messages to social networks
Go
22
star
12

nowplaying-widget

A Spotify Now Playing widget that's accessible with anything that can render a webpage
TypeScript
16
star
13

gulp-inno

Compile Inno Setup scripts using Gulp
HTML
11
star
14

mono-signtool

Drop in replacement for Microsoft's signtool not working in Wine
Go
10
star
15

cargo-gha

Version lock, cache, and run binaries from any Github Release assets. Pull in external tools and keep the versions in sync across your team, and forget installing globally.
Rust
6
star
16

winston-electron

Slightly modified version of Winston Console to work with Electron
JavaScript
4
star
17

cordova-ListMusic

A Cordova/Phonegap/SteroidsJS plugin that lists all tracks in Android's MediaStore (default music player).
Java
3
star
18

wrappers

Small shell wrappers around language tooling to fit my personal preference
Shell
2
star
19

streamwithfriends

StreamWithFriends allows your friends webcams to appear on your stream all through a web broswer
JavaScript
2
star
20

cordova-MusicControl

Control default music player for Android from Cordova/Phonegap/Steroids.
Java
2
star
21

cf-alias

Create Cloudflare email alias' directly from your terminal or Alfred.
Rust
1
star
22

fetch-hls

A quick and lazy solution to proxy HLS streams to external players (Chromecast, VLC).
Go
1
star
23

node-cleverbot

Cleverbot library for Node
JavaScript
1
star
24

homebrew-casks

Custom casks for myself, and anyone else interested
Ruby
1
star
25

pokepush

Pokemon Go push notifications when new Pokemon arrives in specified locations
Go
1
star
26

csgo

Dockerized CSGO Server
Makefile
1
star
27

homebrew-tap

Homebrew forumulaes for my project
Ruby
1
star