OllamaChat - Ruby Chat Bot for Ollama

Description

ollama_chat is a chat client, that can be used to connect to an ollama server and enter chat conversations with the LLMs provided by it.

Documentation

Complete API documentation is available at: GitHub.io

Installation (gem)

To install ollama_chat, you can type

gem install ollama_chat

in your terminal.

Configuration

Environment Variables

The following environment variables can be used to configure behavior:

Ollama Core

  • OLLAMA_URL - Base URL for Ollama server (default: http://localhost:11434)
  • OLLAMA_HOST - Base hostname for Ollama server (default: localhost:11434)
  • OLLAMA_SEARXNG_URL - SearxNG search endpoint URL

Chat Settings

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

Tool Configuration

  • 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_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

System & Infrastructure

  • 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)
  • 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"]}'

Usage

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
  -c CHAT        a saved chat conversation to load
  -C COLLECTION  name of the collection used in this conversation
  -D DOCUMENT    load document and add to embeddings collection (multiple)
  -M             use (empty) MemoryCache for this chat session
  -E             disable embeddings for this chat session
  -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: Advanced Context Injection

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.

1. Understanding "Sources"

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.

2. Subcommands

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.

3. The Power of Patterns (-p)

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.

4. Refining the Input

  • 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.

Examples

Goal Command
Import a single file /input path lib/ollama_chat.rb
Input the output of a command /input !env
Summarize multiple files (Interactive) /input summary -p "spec/**/*_spec.rb"
Bulk import all Ruby files in lib/ /input -p "lib/**/*.rb" -a
Embed a doc into a specific collection /input embedding -c documentation-v1 "docs/api.md"
Import and edit a URL's content /input -e https://example.com/guide
Generate project context for the AI /input context

🚀 Power User Features

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

1. The Character & Persona Engine

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.

2. Intelligent Prompt Engineering (/prompt suggest)

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.

3. Model Profile Orchestration (/model)

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.

4. Conversation Archiving (/session summarize)

Turn your long-form brainstorming sessions into structured documents. The /session summarize command can distill an entire conversation into a concise summary.

  • Quick View: Use -s for a one-sentence executive summary.
  • Archiving: Use -f <filename> to dump the full summary directly into a Markdown file, creating an automatic journal of your project's evolution.

Using a Persona

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?

Using a multimodal model

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

cat

$ 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.

Using ollama_chat_send to send input to a running ollama_chat

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

Advanced Parameters for ollama_chat_send

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

  • 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.

Available Tools

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

Category Tools Description
Filesystem read_file, write_file, patch_file, delete_file, move_file, directory_structure, execute_grep Read, write, and search files within allowed directories.
Ruby/Dev resolve_tag, execute_ri, gem_path_lookup, run_tests, eval_ruby Introspect Ruby code, check documentation, and run test suites.
Web/External search_web, get_url, browse, get_rfc, get_cve, get_endoflife, get_ghr, get_jira_issue Access the internet, fetch specific URLs, and look up technical standards.
System/Util get_time, get_location, get_current_weather, generate_password, compute_bmi, roll_dice General utility functions for time, location, and simple calculations.
Editor/Clip copy_to_clipboard, paste_from_clipboard, paste_into_editor, open_file_in_editor Bridge the gap between the chat and the system clipboard or editor.
Knowledge retrieve_document_snippets, file_context Semantic search for specific snippets vs. broad retrieval of structured project context.
Multimodal generate_image Generate images via a local ComfyUI server.

Note on Knowledge Tools: Use retrieve_document_snippets for precise, low-token semantic discovery and file_context for a comprehensive view of modules or patterns. Be cautious with broad patterns in file_context, as importing too many files can exceed the LLM's context window.

Download

The homepage of this app is located at

Author

OllamaChat was written by Florian Frank

License

This software is licensed under the MIT License.