{"id":13479102,"url":"https://github.com/dustinblackman/oatmeal","last_synced_at":"2025-05-16T09:06:45.655Z","repository":{"id":205874940,"uuid":"714853510","full_name":"dustinblackman/oatmeal","owner":"dustinblackman","description":"Terminal UI to chat with large language models (LLM) using different model backends, and integrations with your favourite editors!","archived":false,"fork":false,"pushed_at":"2024-06-01T03:49:13.000Z","size":1837,"stargazers_count":613,"open_issues_count":24,"forks_count":35,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-13T18:47:59.917Z","etag":null,"topics":["chat","cli","developer-experiance","large-language-models","llm","oatmeal","rust","terminal-ui","tui"],"latest_commit_sha":null,"homepage":"https://dustinblackman.com/posts/oatmeal/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dustinblackman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-06T01:19:04.000Z","updated_at":"2025-05-13T17:30:37.000Z","dependencies_parsed_at":"2023-12-09T01:37:02.232Z","dependency_job_id":"5ef0261e-fcb4-4ec7-bdf5-d7b0914b2cca","html_url":"https://github.com/dustinblackman/oatmeal","commit_stats":null,"previous_names":["dustinblackman/oatmeal"],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustinblackman%2Foatmeal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustinblackman%2Foatmeal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustinblackman%2Foatmeal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustinblackman%2Foatmeal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dustinblackman","download_url":"https://codeload.github.com/dustinblackman/oatmeal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501558,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chat","cli","developer-experiance","large-language-models","llm","oatmeal","rust","terminal-ui","tui"],"created_at":"2024-07-31T16:02:09.412Z","updated_at":"2025-05-16T09:06:40.643Z","avatar_url":"https://github.com/dustinblackman.png","language":"Rust","funding_links":[],"categories":["Rust","💻 Apps"],"sub_categories":["⌨️ Development Tools"],"readme":"\u003ch1 align=center\u003eOatmeal\u003c/h1\u003e\n\n![oatmeal](.github/banner.png)\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/dustinblackman/oatmeal/ci.yml?branch=main)](https://github.com/dustinblackman/oatmeal/actions)\n[![Release](https://img.shields.io/github/v/release/dustinblackman/oatmeal)](https://github.com/dustinblackman/oatmeal/releases)\n[![Coverage Status](https://coveralls.io/repos/github/dustinblackman/oatmeal/badge.svg?branch=main)](https://coveralls.io/github/dustinblackman/oatmeal?branch=main)\n\n\u003e Terminal UI to chat with large language models (LLM) using different model backends, and integrations with your favourite [editors](#editors)!\n\n- [Overview](#Overview)\n- [Install](#Install)\n  - [MacOS](#macos)\n  - [Debian / Ubuntu](#debian--ubuntu)\n  - [Fedora / CentOS](#fedora--centos)\n  - [Nix](#nix)\n  - [Arch Linux](#arch-linux)\n  - [Alpine Linux](#alpine-linux)\n  - [Windows](#windows)\n  - [Cargo](#cargo)\n  - [Docker](#docker)\n  - [Manual](#manual)\n  - [Source](#source)\n- [Usage](#Usage)\n  - [Configuration](#configuration)\n  - [Backends](#backends)\n  - [Editors](#editors)\n  - [Themes](#themes)\n  - [Sessions](#sessions)\n- [Contributing](#contributing)\n  - [Report an issue](#report-an-issue)\n  - [Development](#Development)\n    - [Setup](#setup)\n    - [Adding a backend](#adding-a-backend)\n    - [Adding an editor](#adding-an-editor)\n    - [Adding syntax highlighting for a language](#adding-syntax-highlighting-for-a-language)\n- [FAQ](#faq)\n  - [Why Oatmeal?](#why-oatmeal)\n- [License](#license)\n\n## Overview\n\nOatmeal 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.\nWhile Oatmeal works great as a stand alone terminal application, it works even better paired with an editor like Neovim!\n\nSee it in action with Neovim (click to restart):\n\n![oatmeal-demo](https://github.com/dustinblackman/oatmeal/assets/5246169/9ee5e910-4eff-4deb-8065-aeab8bfe6b00)\n\n_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.\n\n## Install\n\n### macOS\n\n```sh\nbrew install dustinblackman/tap/oatmeal\n```\n\n### Debian / Ubuntu\n\nNote: This method may have outdated releases.\n\n```sh\ncurl -s https://apt.dustinblackman.com/KEY.gpg | apt-key add -\ncurl -s https://apt.dustinblackman.com/dustinblackman.list \u003e /etc/apt/sources.list.d/dustinblackman.list\nsudo apt-get update\nsudo apt-get install oatmeal\n```\n\n### Fedora / CentOS\n\nNote: This method may have outdated releases.\n\n```sh\ndnf config-manager --add-repo https://yum.dustinblackman.com/config.repo\ndnf install oatmeal\n```\n\n### Nix\n\n```sh\nnix-env -f '\u003cnixpkgs\u003e' -iA nur.repos.dustinblackman.oatmeal\n```\n\n### Arch Linux\n\n```sh\nyay -S oatmeal-bin\n```\n\n### Alpine Linux\n\n\u003c!-- alpine-install start --\u003e\n\n```sh\narch=$(uname -a | grep -q aarch64 \u0026\u0026 echo 'arm64' || echo 'amd64')\ncurl -L -o oatmeal.apk \"https://github.com/dustinblackman/oatmeal/releases/download/v0.13.0/oatmeal_0.13.0_linux_${arch}.apk\"\napk add --allow-untrusted ./oatmeal.apk\n```\n\n\u003c!-- alpine-install end --\u003e\n\n### Windows\n\n**Chocolatey**\n\n\u003c!-- choco-install start --\u003e\n\n```sh\nchoco install oatmeal --version=0.13.0\n```\n\n\u003c!-- choco-install end --\u003e\n\n**Scoop**\n\n```sh\nscoop bucket add dustinblackman https://github.com/dustinblackman/scoop-bucket.git\nscoop install oatmeal\n```\n\n**Winget**\n\n```sh\nwinget install -e --id dustinblackman.oatmeal\n```\n\n### Cargo\n\n```sh\ncargo install oatmeal --locked\n```\n\n### Docker\n\n```sh\ndocker run --rm -it ghcr.io/dustinblackman/oatmeal:latest\n```\n\n### Manual\n\nDownload the pre-compiled binaries and packages from the [releases page](https://github.com/dustinblackman/oatmeal/releases) and\ncopy to the desired location.\n\n### Source\n\n```sh\ngit clone https://github.com/dustinblackman/oatmeal.git\ncd oatmeal\ncargo build --release\nmv ./target/release/oatmeal /usr/local/bin/\n```\n\n## Usage\n\nThe following shows the available options to start a chat session. By default when running `oatmeal`, Ollama is the selected backend, and the `clipboard` integration for an editor.\nSee `oatmeal --help`, `/help` in chat, or the output below to get all the details.\n\n\u003c!-- command-help start --\u003e\n\n```\nTerminal UI to chat with large language models (LLM) using different model backends, and direct integrations with your favourite editors!\n\nVersion: 0.13.0\nCommit: v0.13.0\n\nUsage: oatmeal [OPTIONS] [COMMAND]\n\nCommands:\n  chat         Start a new chat session.\n  completions  Generates shell completions.\n  config       Configuration file options.\n  manpages     Generates manpages and outputs to stdout.\n  sessions     Manage past chat sessions.\n  help         Print this message or the help of the given subcommand(s)\n\nOptions:\n  -b, --backend \u003cbackend\u003e\n          The initial backend hosting a model to connect to. [default: ollama] [env: OATMEAL_BACKEND=] [possible values: langchain, ollama, openai, claude, gemini]\n      --backend-health-check-timeout \u003cbackend-health-check-timeout\u003e\n          Time to wait in milliseconds before timing out when doing a healthcheck for a backend. [default: 1000] [env: OATMEAL_BACKEND_HEALTH_CHECK_TIMEOUT=]\n  -m, --model \u003cmodel\u003e\n          The initial model on a backend to consume. Defaults to the first model available from the backend if not set. [env: OATMEAL_MODEL=]\n  -c, --config-file \u003cconfig-file\u003e\n          Path to configuration file [default: ~/.config/oatmeal/config.toml] [env: OATMEAL_CONFIG_FILE=]\n  -e, --editor \u003ceditor\u003e\n          The editor to integrate with. [default: clipboard] [env: OATMEAL_EDITOR=] [possible values: neovim, clipboard, none]\n  -t, --theme \u003ctheme\u003e\n          Sets code syntax highlighting theme. [default: base16-onedark] [env: OATMEAL_THEME=] [possible values: base16-github, base16-monokai, base16-one-light, base16-onedark, base16-seti]\n      --theme-file \u003ctheme-file\u003e\n          Absolute path to a TextMate tmTheme to use for code syntax highlighting. [env: OATMEAL_THEME_FILE=]\n      --lang-chain-url \u003clang-chain-url\u003e\n          LangChain Serve API URL when using the LangChain backend. [default: http://localhost:8000] [env: OATMEAL_LANGCHAIN_URL=]\n      --ollama-url \u003collama-url\u003e\n          Ollama API URL when using the Ollama backend. [default: http://localhost:11434] [env: OATMEAL_OLLAMA_URL=]\n      --open-ai-url \u003copen-ai-url\u003e\n          OpenAI API URL when using the OpenAI backend. Can be swapped to a compatible proxy. [default: https://api.openai.com] [env: OATMEAL_OPENAI_URL=]\n      --open-ai-token \u003copen-ai-token\u003e\n          OpenAI API token when using the OpenAI backend. [env: OATMEAL_OPENAI_TOKEN=]\n      --claude-token \u003cclaude-token\u003e\n          Anthropic's Claude API token when using the Claude backend. [env: OATMEAL_CLAUDE_TOKEN=]\n      --gemini-token \u003cgemini-token\u003e\n          Google Gemini API token when using the Gemini backend. [env: OATMEAL_GEMINI_TOKEN=]\n  -h, --help\n          Print help\n  -V, --version\n          Print version\n\nCHAT COMMANDS:\n  - /modellist (/ml) - Lists all available models from the backend.\n  - /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`.\n  - /append (/a) [CODE_BLOCK_NUMBER?] - Appends code blocks to an editor. See Code Actions for more details.\n  - /replace (/r) [CODE_BLOCK_NUMBER?] - Replaces selections with code blocks in an editor. See Code Actions for more details.\n  - /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.\n  - /quit /exit (/q) - Exit Oatmeal.\n  - /help (/h) - Provides this help menu.\n\nCHAT HOTKEYS:\n  - Up arrow - Scroll up.\n  - Down arrow - Scroll down.\n  - CTRL+U - Page up.\n  - CTRL+D - Page down.\n  - CTRL+C - Interrupt waiting for prompt response if in progress, otherwise exit.\n  - CTRL+O - Insert a line break at the cursor position.\n  - CTRL+R - Resubmit your last message to the backend.\n\nCHAT CODE ACTIONS:\nWhen 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.\n\n  - /append (/a) [CODE_BLOCK_NUMBER?] will append one-to-many model provided code blocks to the open file in your editor.\n  - /replace (/r) [CODE_BLOCK_NUMBER?] - will replace selected code in your editor with one-to-many model provided code blocks.\n  - /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.\n\nThe `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:\n  - `1` - Selects the first code block\n  - `1,3,5` - Selects code blocks 1, 3, and 5.\n  - `2..5`- Selects an inclusive range of code blocks between 2 and 5.\n  - None - Selects the last provided code block.\n```\n\n\u003c!-- command-help end --\u003e\n\n### Configuration\n\nOn top of being configurable with command flags and environment variables, Oatmeal is also manageable with a\nconfiguration file such as [this example](./config.example.toml). You can run `oatmeal config create` to initialize for\nthe first time.\n\n\u003c!-- command-config start --\u003e\n\n```\nConfiguration file options.\n\nUsage: oatmeal config [OPTIONS] [COMMAND]\n\nCommands:\n  create   Saves the default config file to the configuration file path. This command will fail if the file exists already.\n  default  Outputs the default configuration file to stdout.\n  path     Returns the default path for the configuration file.\n  help     Print this message or the help of the given subcommand(s)\n```\n\n\u003c!-- command-config end --\u003e\n\n### Backends\n\nThe following model backends are supported:\n\n- [OpenAI](https://chat.openai.com) (Or any compatible proxy/API)\n- [Ollama](https://github.com/jmorganca/ollama)\n- [LangChain/LangServe](https://python.langchain.com/docs/langserve) (Experimental)\n- [Claude](https://claude.ai) (Experimental)\n- [Gemini](https://gemini.google.com) (Experimental)\n\n### Editors\n\nThe following editors are currently supported. The `clipboard` editor is a special case where any copy or accept commands\nare simply copied to your clipboard. This is the default behaviour. Hit any of the links below for more details on how\nto use!\n\n- Clipboard (Default)\n- None (Disables all editor functionality)\n- [Neovim](https://github.com/dustinblackman/oatmeal.nvim)\n\n### Themes\n\nA handful of themes are embedded in the application for code syntax highlighting, defaulting to [OneDark](https://github.com/atom/one-dark-ui). If none suits your needs, Oatmeal supports any Sublime Text/Text Mate\n`.tmTheme` file with the `theme-file` configuration option. [base16-textmate](https://github.com/chriskempson/base16-textmate) has plenty to pick from!\n\n### Sessions\n\nOatmeal persists all chat sessions with your models, allowing you to go back and review an old conversation, or pick up\nfrom where you left off!\n\n\u003c!-- command-help-sessions start --\u003e\n\n```\nManage past chat sessions.\n\nUsage: oatmeal sessions [OPTIONS] [COMMAND]\n\nCommands:\n  dir     Print the sessions cache directory path.\n  list    List all previous sessions with their ids and models.\n  open    Open a previous session by ID. Omit passing any session ID to load an interactive selection.\n  delete  Delete one or all sessions.\n  help    Print this message or the help of the given subcommand(s)\n```\n\n\u003c!-- command-help-sessions end --\u003e\n\nGrepping through previous sessions isn't something built in to Oatmeal _(yet)_. This bash function can get you there\nnicely using [Ripgrep](https://github.com/BurntSushi/ripgrep) and [FZF](https://github.com/junegunn/fzf).\n\n```bash\nfunction oatmeal-sessions() {\n    (\n        cd \"$(oatmeal sessions dir)\"\n        id=$(rg --color always -n . | fzf --ansi | awk -F ':' '{print $1}' | head -n1 | awk -F '.' '{print $1}')\n        oatmeal sessions open --id \"$id\"\n    )\n}\n```\n\nOr something a little more in depth (while hacky) that additionally uses [yq](https://github.com/mikefarah/yq) and [jq](https://github.com/jqlang/jq).\n\n```bash\nfunction oatmeal-sessions() {\n    (\n        cd \"$(oatmeal sessions dir)\"\n        id=$(\n          ls | \\\n          (while read f; do echo \"$(cat $f)\\n---\\n\"; done;) | \\\n          yq -p=yaml -o=json - 2\u003e /dev/null | \\\n          jq -s . | \\\n          jq -rc '. |= sort_by(.timestamp) | .[] |  \"\\(.id):\\(.timestamp):\\(.state.backend_model):\\(.state.editor_language):\\(.state.messages[] | .text | tojson)\"' | \\\n          fzf --ansi | \\\n          awk -F ':' '{print $1}' | \\\n          head -n1 | \\\n          awk -F '.' '{print $1}'\n        )\n        oatmeal sessions open --id \"$id\"\n    )\n}\n```\n\n## Contributing\n\n### Report an issue\n\nOn each Oatmeal release there is a separate download to help in reporting issues to really drill down in to what the\nproblem is! If you've run in to a problem, I'd really help appreciate solving it.\n\n1. Head over to [releases](https://github.com/dustinblackman/oatmeal/releases) and download the DEBUG package for the\n   latest release of Oatmeal.\n2. Extract the contents of the archive, and `cd` in your terminal inside the archive.\n3. Run your command with the arguments provided in the error message prefixing with `RUST_BACKTRACE=1 ./oatmeal **ARGS-HERE**`\n4. Copy/paste the output and [open an issue](https://github.com/dustinblackman/oatmeal/issues/new). Include any screenshots you believe will be helpful!\n\n### Development\n\n#### Setup\n\n[![Open in DevPod!](.github/devpod.svg)](https://devpod.sh/open#https://github.com/dustinblackman/oatmeal)\n\nOatmeal comes with a ready made DevContainer with all the magic needed to work on the project. However if you wish to develop fully local, the following will get you set up with all the necessary tooling.\n\n```sh\ncargo install cargo-run-bin\ngit clone https://github.com/dustinblackman/oatmeal.git\ncd oatmeal\ncargo cmd setup\n```\n\n#### Adding a backend\n\nEach backend implements the [Backend trait](./src/domain/models/backend.rs) in its own infrastructure file. The trait has documentation on what is expected of each method. You can checkout [Ollama](./src/infrastructure/backends/ollama.rs) as an example.\n\nThe following steps should be completed to add a backend:\n\n1. Implement trait for new backend.\n2. Update the [BackendName](./src/domain/models/backend.rs) enum with your new Backend name.\n3. Update the [BackendManager](./src/infrastructure/backends/mod.rs) to provide your new backend.\n4. Write tests\n\n#### Adding an editor\n\nEach editor implements the [Editor trait](./src/domain/models/editor.rs) in its own infrastructure file. The trait has documentation on what is expected of each method. You can checkout [Neovim](./src/infrastructure/editors/neovim.rs) as an example.\n\nThe following steps should be completed to add an editor:\n\n1. Implement trait for new editor.\n2. Update the [EditorName](./src/domain/models/editor.rs) enum with your new Editor name.\n3. Update the [EditorManager](./src/infrastructure/editors/mod.rs) to provide your new editor.\n4. Write tests\n\n#### Adding syntax highlighting for a language\n\nSyntax highlighting language selection is a tad manual where several languages must be curated and then added to\n[`assets.toml`](./assets.toml).\n\n1. Google to find a `.sublime-syntax` project on GitHub for your language. [bat](https://github.com/sharkdp/bat/tree/master/assets/syntaxes/02_Extra) has many!\n2. Update [`assets.toml`](./assets.toml) to include the new repo. Make sure to include the license in the files array.\n   You can leave `nix-hash` as an empty string, and it'll be updated by a maintainer later. Or if you have docker\n   installed, you can run `cargo xtask hash-assets`.\n3. `rm -rf .caches \u0026\u0026 cargo build`\n4. Test to see highlighting works.\n\n## FAQ\n\n### Why Oatmeal?\n\nI was eating a bowl of oatmeal when I wrote the first commit :shrug:. (They don't let me name things at work anymore...)\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdustinblackman%2Foatmeal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdustinblackman%2Foatmeal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdustinblackman%2Foatmeal/lists"}