OllamaChat - Ruby Chat Bot for Ollama

ollama_chat is a terminal chat client that connects to an Ollama server and lets you converse with the LLMs it provides.

Complete API documentation is available at: GitHub.io

To install ollama_chat, you can type

gem install ollama_chat

in your terminal.

After gem update ollama_chat, the next launch will either start cleanly or prompt you to fix the config:

1. Open the config diff. Run /config diff, or wait for the automatic fix_config prompt if the new version introduced required keys. Either way, your $DIFF_TOOL (default: vimdiff) opens with your local config.yml on one side and the shipped default_config.yml on the other.

2. Pull in the changes. In vimdiff, use :diffget to copy new or updated keys from the default into your local file. Ignore keys you've intentionally overridden.

3. Reload. Close the diff tool and answer y to the "restart?" prompt.

4. Prompt drift. If the new version changed any shipped prompts, a fingerprint notice lists modified, added, and removed prompts. To reconcile your stored prompts with the new defaults, run /prompt sync. It diffs each prompt against the shipped version and lets you decide per prompt: adopt the new default, keep your local edit, or review the change. After syncing, the fingerprint is updated and the nagging stops.

   If you simply want to dismiss the notice without syncing, answer y to the boot prompt. The fingerprint is stored and you won't be asked again.

Your local config is a partial override. Keys you don't have fall through to the shipped defaults. No migration script needed.

The following environment variables can be used to configure behavior:

• OLLAMA_URL - Base URL for Ollama server (default: http://localhost:11434)
• OLLAMA_HOST - Base hostname for Ollama server (default: localhost:11434)
• OLLAMA_EMBEDDING_URL - Optional base URL for a dedicated Ollama server used exclusively for embedding operations. When set, the embedding model runs on this host while the chat model stays on OLLAMA_URL. Falls back to OLLAMA_URL when unset.
• OLLAMA_SEARXNG_URL - SearxNG search endpoint URL
• OLLAMA_CHAT_TTS_URL - Base URL for the audio.cpp TTS server (default: http://localhost:8880)

• OLLAMA_CHAT_MODEL - Default model to use (e.g., llama3.1)
• OLLAMA_CHAT_SYSTEM - Default system prompt file or content
• OLLAMA_CHAT_COLLECTION - Default collection for embeddings
• OLLAMA_CHAT_HISTORY - Chat history filename
• OLLAMA_CHAT_USER - Full name of the chat user
• OLLAMA_CHAT_DEBUG - Debug mode toggle (1 = enabled)
• OLLAMA_CHAT_LOG_CHAT - Chat log file path (default: $XDG_STATE_HOME/chat.log)
• OLLAMA_CHAT_LOG_DATABASE - Database log file path (default: $XDG_STATE_HOME/database.log)
• OLLAMA_CHAT_LOG_TAIL_LINES - Max lines to retain in log files (default: 10000)

• OLLAMA_CHAT_ASR_URL - Base URL for the ASR (Speech-to-Text) service (default: http://localhost:8880)
• OLLAMA_CHAT_ASR_CONVERT_COMMAND - Shell command template to convert video to 16 kHz mono PCM WAV; use %{input} / %{output} as placeholders (default: ffmpeg -y -i %{input} -vn -acodec pcm_s16le -ar 16000 -ac 1 %{output})
• OLLAMA_CHAT_ASR_MODEL - ASR model identifier (default: qwen3-asr-1.7b)

• OLLAMA_CHAT_AUDIO_PLAYER_CONFIG - JSON object with command, frequency, bits, pause keys controlling the ffplay-based TTS audio player

• OLLAMA_CHAT_INVIDIOUS_URL - Base URL for an Invidious instance
• OLLAMA_CHAT_INVIDIOUS_COMPANION_KEY - Bearer token for the Invidious companion player API (required when URL is set)
• OLLAMA_CHAT_INVIDIOUS_CAPTION_LANGUAGES - JSON array of language-code regexes for caption selection priority (default: ["\\Aen\\z","\\Aen-","\\Ade\\z","\\Ade-"])

• OLLAMA_CHAT_TOOLS_TEST_RUNNER - Configured test runner for run_tests (default: rspec)
• OLLAMA_CHAT_TOOLS_CTAGS_TOOL - Path to the ctags tool
• OLLAMA_CHAT_TOOLS_TAGS_FILE - Location of the tags file
• OLLAMA_CHAT_TOOLS_JIRA_URL - Base URL for Jira instance
• OLLAMA_CHAT_TOOLS_JIRA_USER - Username for Jira authentication
• OLLAMA_CHAT_TOOLS_JIRA_API_TOKEN - API token for Jira authentication
• OLLAMA_CHAT_TOOLS_JIRA_TWG - Path to the twg CLI binary
• OLLAMA_CHAT_TOOLS_IMAGE_GENERATOR_URL - Base URL for ComfyUI server
• OLLAMA_CHAT_TOOLS_IMAGE_GENERATOR_WORKFLOW - ComfyUI workflow as JSON string
• OLLAMA_CHAT_TOOLS_IMAGE_GENERATOR_PROMPT_NODE_ID - Prompt node ID
• OLLAMA_CHAT_TOOLS_IMAGE_GENERATOR_FILENAME_PREFIX_NODE_ID - Filename prefix node ID
• OLLAMA_CHAT_TOOLS_PIRATEWEATHER_API_KEY - Pirate Weather API key
• OLLAMA_CHAT_TOOLS_GHR_URL - Base URL for GHR API server
• OLLAMA_CHAT_TOOLS_RUBY_EVAL_IMAGE_TEMPLATE - Docker image template for eval_ruby (default: ruby:%{version}-alpine)

• XDG_CONFIG_HOME - XDG Configuration home directory
• XDG_CACHE_HOME - XDG Cache home directory
• XDG_STATE_HOME - XDG State home directory
• PAGER - Default pager for output
• EDITOR - Default text editor
• BROWSER - Default web browser
• DIFF_TOOL - Tool for diff operations (default: vimdiff)
• DIFF_COMMAND - Command to generate unified diffs (default: diff -u --color=always)
• KRAMDOWN_ANSI_OLLAMA_CHAT_STYLES - Custom ANSI styles for Markdown formatting
• KRAMDOWN_ANSI_STYLES - Fallback ANSI styles configuration
• OLLAMA_REDIS_URL - Redis connection URL for documents (documentrix)
• OLLAMA_REDIS_EXPIRING_URL - Optional Redis connection URL for caching

Example usage for KRAMDOWN_ANSI_OLLAMA_CHAT_STYLES:

# Set custom ANSI colors for Markdown output as a JSON object:
export KRAMDOWN_ANSI_OLLAMA_CHAT_STYLES='{"header":["bold","on_color241","white"],"strong":["bold","color76"],"em":["italic","color227"],"code":["bold","color214"]}'

It can be started with the following arguments:

Usage: ollama_chat [OPTIONS]

  -f CONFIG      config file to read
  -l SESSION     load session with name/id SESSION
  -n             create a new session
  -u URL         the ollama base url, OLLAMA_URL
  -m MODEL       the ollama model to chat with, OLLAMA_CHAT_MODEL, ?selector
  -S             open a socket to receive input from ollama_chat_send
  -V             display the current version number and quit
  -h             this help

  Use `?selector` with `-m` or `-l` to filter options. Multiple matches
  will open a chooser dialog.

The base URL can be either set by the environment variable OLLAMA_URL or it is derived from the environment variable OLLAMA_HOST. The default model to connect can be configured in the environment variable OLLAMA_CHAT_MODEL.

The YAML config file is stored in $XDG_CONFIG_HOME/ollama_chat/config.yml and you can use it for more complex settings.

The /input command is a versatile tool designed to bring external data into your conversation context. Instead of manually copying and pasting, /input allows you to target files, URLs, or even live system output using powerful filters.

One of the most powerful aspects of /input is its definition of a source. A source isn't just a filename; it can be any of the following:

• Local Files: Standard paths (e.g., lib/ollama_chat.rb) or quoted paths for those with spaces.
• Remote URLs: Any http:// or https:// link. The command will fetch the web content and parse it before importing.
• Shell Commands (!): Any source starting with an exclamation mark is executed as a shell command, and its STDOUT is imported as the content.
  • Example: /input !ls -la imports the current directory listing.
  • Example: /input !git branch tells the AI which branch you are on.

Depending on how you want the AI to "see" the data, you can use different subcommands:

• import (Default): The standard way to bring content in. It reads the source and formats it for the chat.
• path: Specifically targets local files to read their raw content.
• summary: Instead of importing the whole file, this uses the LLM to generate a concise summary first. Use -w <words> to control the length (default: 100).
• embedding: Sends the content directly into your RAG vector database rather than the immediate chat window. Use -c <collection> for specific collections and -t <tags> to categorize the data.
• context: Uses ContextSpook to generate a comprehensive structural dump of your project, providing both the architectural skeleton and full file contents in a high-density format.

By adding the -p flag, you can use Unix-style globs to select multiple files at once.

• Interactive Selection: By default, when using patterns, ollama_chat will present an interactive menu allowing you to pick exactly which matching files you want to import.
• Bulk Import (-a): Use the -a (all) flag alongside -p to bypass the menu and import every file that matches the pattern automatically.

• Editing on the Fly (-e): For the import and path subcommands, you can use the -e flag. This opens the content in your default editor, allowing you to trim or modify the text before it is sent to the LLM.
• Custom Tags: When embedding, tags allow you to create "slices" of knowledge that can be retrieved later based on specific categories.

Beyond basic chat, ollama_chat includes several advanced systems designed for high-end AI orchestration and personalization.

The bot supports a sophisticated roleplay system that goes beyond simple text prompts.

• SillyTavern Compatibility (/character): You can import character cards directly from PNG or JSON files. This supports the SillyTavern standard, allowing you to load entire personalities—including metadata and example dialogues—embedded within an image file.
  • Example: /character import fluffy.png
• Persona Management (/persona): Create, duplicate, and export complex persona profiles. You can use /persona play to activate a personality as your default for the session.

Instead of guessing the right prompt, you can let the AI help you write one. The suggest subcommand analyzes your current session history and utilizes specialized strategies (like suggest_coding or suggest_roleplaying) to generate a tailored prompt template for you to refine.

Avoid the tedious task of re-configuring model parameters every time you switch. The profile system allows you to manage "Live" vs "Saved" settings:

• Saved -> Live: Apply a pre-configured profile's settings (temperature, top_p, etc.) to your current session using options to session.
• Live -> Saved: After fine-tuning your model's behavior during a chat, "bake" those live settings into a permanent profile using options from session.

Turn your long-form brainstorming sessions into structured documents. The /conversation summarize command distills an entire conversation into a concise summary, displayed in the pager first, then optionally saved.

• Quick View: Use -s for a one-sentence executive summary.
• Archiving: After the summary is displayed, you are prompted for a filename to save it as a Markdown file, creating an automatic journal of your project's evolution.

Long sessions inevitably fill up the model's context window. The /conversation compact command summarizes older messages into a single compact summary while preserving recent exchanges, freeing up space for continued work.

• Token-aware: The keep-recent budget is derived from the active model's context length, so it adapts automatically.
• Safe & retryable: If the LLM summarization fails, the message list is left untouched and you can simply retry.
• Visible metrics: After compaction, a report shows summarized message count, summary size, and context usage before/after.
• Iterative: Repeated compactions merge into the existing summary rather than stacking multiple summary messages.

Run it whenever context usage climbs into the red zone (visible in the runtime info gauge) — the model stays sharp and the conversation keeps flowing.

If compaction alone isn't enough, a practical escalation ladder:

1. /conversation compact — summarize old messages, keep recent tail. Try this first; it's the least destructive.
2. /conversation report → /clear → /input path standup.md — generate a standup-style report, save it, clear the messages, then feed the report back as context. Do this before clean, because clean strips the tool output and thinking that make a good report.
3. /conversation clean — strips tool results, images, and thinking content from all messages. More radical, but the conversation structure and text remain intact. The emergency exit: if context is so stuffed that even a report can't fit, clean carves out enough room for anything to work again.

Generate a structured report from your conversation using configurable prompt templates. The report is displayed in the pager first, then optionally saved to a file. Particularly useful for daily standup summaries — run it at the end of the day and save the output for your team sync.

You can import a persona profile from a Markdown file and load it into the current session. The persona's content is then interpolated into the system prompt (which defaults to "%{persona}") as %{persona}. You can set your own system prompts and interpolate the persona like this:

You are a helpful assistant.

%{persona}

The following interaction demonstrates how to import a persona file, activate it, and start the conversation:

$ ollama_chat
Connecting to llama3.1@http://localhost:11434 now…
Type /help to display the chat help.
📨 user:
/persona import config/sherlock.md
# (Prompts for name: "sherlock")
Persona 'sherlock' imported successfully.
📨 user:
/persona
# (Select 'sherlock' from the list to be impersonated by the assistant)
📨 user:
Good morning.
📨 assistant:
Ah, good morning, my dear fellow! It is a pleasure to make your acquaintance. I
am Sherlock Holmes, the renowned detective, and this is my trusty sidekick, Dr.
Watson. Please, have a seat, and tell us about the nature of your visit. What
seems to be the problem that has brought you to our humble abode at 221B Baker
Street?

This example shows how an image like this can be sent to the LLM for multimodal analysis:

$ ollama_chat -m llava-llama3
Model with architecture llama found.
Connecting to llava-llama3@http://localhost:11434 now…
Type /help to display the chat help.
📸 user> What's on this image? ./spec/assets/kitten.jpg
📨 assistant:
The image captures a moment of tranquility featuring a young cat. The cat,
adorned with gray and white fur marked by black stripes on its face and legs,
is the central figure in this scene. Its eyes, a striking shade of blue, are
wide open and directed towards the camera, giving an impression of curiosity or
alertness.

The cat is comfortably nestled on a red blanket, which contrasts vividly with
its fur. The blanket, soft and inviting, provides a sense of warmth to the
image. In the background, partially obscured by the cat's head, is another
blanket of similar red hue. The repetition of the color adds a sense of harmony
to the composition.

The cat's position on the right side of the photo creates an interesting
asymmetry with the camera lens, which occupies the left side of the frame. This
visual balance enhances the overall composition of the image.

There are no discernible texts or other objects in the image. The focus is
solely on the cat and its immediate surroundings. The image does not provide
any information about the location or setting beyond what has been described.
The simplicity of the scene allows the viewer to concentrate on the main
subject - the young, blue-eyed cat.

You can do this from the shell by pasting into the ollama_chat_send executable.

$ echo "Why is the sky blue?" | ollama_chat_send

To send a text from inside a vim buffer, you can use a function/leader like this:

map <leader>o :<C-U>call OllamaChatSend(@*)<CR>

function! OllamaChatSend(input)
  let input = "Take note of the following code snippet (" . &filetype . ") **AND** await further instructions:\n\n```\n" . a:input . "\n```\n"
  call system('ollama_chat_send', input)
endfunction

The ollama_chat_send command now supports additional parameters to enhance functionality:

• Terminal Input (-t): Sends input as terminal commands, enabling special commands like /input.

  $ echo "/input https://example.com/some-content" | ollama_chat_send -t

• Wait for Response (-r): Enables two-way communication by waiting for and returning the server's response.

  $ response=$(echo "Tell me a joke." | ollama_chat_send -r)
  $ echo "$response"

• Source Parsing (-p): Enables automatic parsing of URLs, file paths, and similar tokens in input content. When enabled, the system will attempt to resolve and include external resources.

  $ echo "Visit https://example.com for more info" | ollama_chat_send -p

• Working Directory (-d): Specifies the working directory used to derive the Unix socket file path. When the ollama chat configuration is set to use a working directory dependent socket (via working_dir_dependent_socket: true), this option determines the base path for socket naming. If not specified, the current working directory is assumed.

  $ echo "Hello world" | ollama_chat_send -d /tmp/my_working_dir -r

• Edit Content (-e): Opens the input content in the configured editor before sending. This is useful for refining the message or adding more context.

  $ echo "Draft message..." | ollama_chat_send -e

• File Format (-F): When using edit mode, specify a file extension to enable syntax highlighting in your editor (e.g., rb for Ruby, md for Markdown).

  $ echo "def hello; end" | ollama_chat_send -e -F rb

• Help (-h or --help): Displays usage information and available options.

  $ ollama_chat_send -h

These parameters provide greater flexibility in how you interact with ollama_chat, whether from the command line or integrated tools like vim.

OllamaChat produces structured JSON logs that capture every tool execution, conversation state, and internal event. The ollama_chat_log utility allows you to filter, colorize, and tail these logs in real-time, displaying the full structured data payload by default.

By default, ollama_chat_log reads the current session's log file located at ~/.local/state/ollama_chat/chat.json (or wherever the default points).

# Show the last 10 log entries
$ ollama_chat_log

# Show the last 50 entries
$ ollama_chat_log -n 50

Use the -f flag to follow the log file as new entries are appended, similar to tail -f.

$ ollama_chat_log -f

The -m flag allows you to filter logs based on nested JSON paths using dot notation. You can match for key presence or substring matches within values.

• Key Presence: -m "data.tool" (shows only logs that have a tool key)
• Substring Match: -m "data.tool=read_file" (shows logs where the tool is read_file)
• Nested Paths: -m "data.function.name=patch_file"
• Regexp Match: -m "data.tool=^(write_file|patch_file)$"

You can chain multiple -m flags together. All patterns must match for a log entry to be displayed (AND logic).

# Show only successful file reads
$ ollama_chat_log -m "data.tool=read_file" -m "level=info"

# Follow and watch for specific tool executions
$ ollama_chat_log -f -m "data.tool=execute_grep"

The assistant can interact with the system using a variety of tools to gather context, manipulate files, and retrieve external information.

Note on Knowledge Tools: Use search_knowledge for low-token semantic discovery. For comprehensive project context, use the /input context command instead of loading files into the tool call context window.

ollama_chat invokes several external executables at runtime. Most are optional and only required for specific features; the app degrades gracefully when they are absent.

# Core (usually already present)
sudo apt install git vim vimdiff diff

# TTS (audio.cpp handler)
sudo apt install ffmpeg

# Clipboard
# ctc is a small helper; see the project README or install from source

# Document parsing
sudo apt install pandoc ghostscript

# Symbol resolution
sudo apt install universal-ctags

# eval_ruby
sudo apt install docker.io

The homepage of this app is located at

• https://github.com/flori/ollama_chat

OllamaChat was written by Florian Frank

This software is licensed under the MIT License.