ollama_agent

Version: 0.1.0

Ruby gem that runs a CLI coding agent against a local Ollama model. It exposes tools to list files, read files, search the tree (ripgrep or grep), and apply unified diffs so the model can make small, reviewable edits.

• Tool list_files – list project files.
• Tool read_file – read file contents.
• Tool search_code – search code with ripgrep or grep.
• Tool edit_file – apply unified diffs safely.
• CLI built with Thor, entry point exe/ollama_agent.
• self_review – self-review / improvement with a --mode:
  • analysis (default, alias 1) — read-only tools; report only; no writes.
  • interactive (alias 2, fix) — full tools on --root; you confirm each patch (like ask); optional -y / --semi.
  • automated (alias 3, sandbox) — temp copy, agent edits, bundle exec rspec in the sandbox, optional --apply to merge into your checkout.
• improve — same as self_review --mode automated (you can pass --mode automated explicitly; other modes belong on self_review).

• Ruby ≥ 3.2 (enforced in the gemspec as required_ruby_version)
• Local: Ollama running and a capable tool-calling model, or
• Ollama Cloud: API key and a cloud-capable model name (see below)

• patch — required for edit_file (GNU patch on PATH). On Windows, use Git Bash, WSL, GnuWin32, or another environment that provides patch.
• rg (ripgrep) or grep — text mode for search_code needs at least one of these on PATH (ripgrep is preferred when present).

From RubyGems (when published) or from this repository:

bundle install

From the project you want the agent to modify (set the working directory accordingly):

bundle exec ruby exe/ollama_agent ask "Update the README.md with current codebase"

From this repository after bundle install, ruby exe/ollama_agent (without bundle exec) also works: the executable adds lib to the load path and loads bundler/setup when a Gemfile is present.

Apply proposed patches without interactive confirmation:

bundle exec ruby exe/ollama_agent ask -y "Your task"

Long-running models (slow local inference):

bundle exec ruby exe/ollama_agent ask --timeout 300 "Your task"

Interactive REPL:

bundle exec ruby exe/ollama_agent ask --interactive

Self-review modes (default project root is the loaded gem tree unless you set --root or OLLAMA_AGENT_ROOT):

# Mode 1 — analysis only (default)
bundle exec ruby exe/ollama_agent self_review
bundle exec ruby exe/ollama_agent self_review --mode analysis

# Mode 2 — optional fixes in the working tree (confirm each patch, or -y / --semi)
bundle exec ruby exe/ollama_agent self_review --mode interactive

# Mode 3 — sandbox + tests + optional merge back (same as `improve`)
bundle exec ruby exe/ollama_agent self_review --mode automated
bundle exec ruby exe/ollama_agent improve --apply

For mode 3, -y skips all patch prompts; --no-semi prompts for every patch when not using -y.

With a thinking-capable model, enable reasoning output:

OLLAMA_AGENT_THINK=true bundle exec ruby exe/ollama_agent ask -i
# or
bundle exec ruby exe/ollama_agent ask -i --think true

The CLI uses ANSI colors on a TTY (banner, prompt, patch prompts). Assistant replies are rendered as Markdown (headings, lists, bold, code fences) via tty-markdown when stdout is a TTY and NO_COLOR is unset. Disable Markdown rendering with OLLAMA_AGENT_MARKDOWN=0. Disable all colors with NO_COLOR or OLLAMA_AGENT_COLOR=0.

When thinking is enabled, internal reasoning is shown in a framed, dim block labeled Thinking; the user-facing reply is labeled Assistant in green when the model returns both fields. Thinking text is plain dim by default (so it stays visually separate from the reply). Set OLLAMA_AGENT_THINKING_MARKDOWN=1 to render thinking through Markdown too (muted colors).

Ollama Cloud uses the same HTTP API as the local server, with HTTPS and a Bearer API key. The ollama-client gem sends Authorization: Bearer <api_key> when Ollama::Config#api_key is set (HTTPS is used when the URL scheme is https).

1. Create a key at ollama.com/settings/keys.
2. Point the agent at the cloud host and pass the key (same env names as ollama-client’s docs):

export OLLAMA_BASE_URL="https://ollama.com"
export OLLAMA_API_KEY="your_key"
export OLLAMA_AGENT_MODEL="gpt-oss:120b-cloud"   # example; pick a cloud model from `ollama list` / the catalog
bundle exec ruby exe/ollama_agent ask "Your task"

• Use a tool-capable model — Set OLLAMA_AGENT_MODEL to a model that supports function/tool calling (e.g. a recent coder-tuned variant). If the model only prints {"name": "read_file", ...} in plain text, tools never run unless you enable OLLAMA_AGENT_PARSE_TOOL_JSON=1.
• Malformed diffs — Headers must look like git diff: --- a/file then +++ b/file then a unified hunk line starting with @@ (not legacy --- N,M ----). Do not put commas after path tokens. The gem normalizes some mistakes and runs patch --dry-run before applying.
• Request timeouts — The agent defaults to a 120s HTTP timeout (longer than ollama-client’s 30s). If you still hit Ollama::TimeoutError, raise it with OLLAMA_AGENT_TIMEOUT=300, bundle exec ruby exe/ollama_agent ask --timeout 300 "...", or -t 300. Ensure the variable name is exactly OLLAMA_AGENT_TIMEOUT (a leading typo such as vOLLAMA_AGENT_TIMEOUT is ignored).

1. The CLI starts OllamaAgent::Agent, which loops on Ollama::Client#chat with tool definitions.
2. Tools are executed in-process under a path sandbox (OLLAMA_AGENT_ROOT).
3. search_code defaults to ripgrep/grep (mode omitted or text). For Ruby, use mode method, class, module, or constant to query a Prism parse index (built lazily on first use). read_file accepts optional start_line / end_line (1-based, inclusive) to read only part of a file.
4. Patches are validated and checked with patch --dry-run before you confirm (unless -y).

bundle exec rspec
bundle exec rubocop

• CI — .github/workflows/main.yml runs RSpec and RuboCop on pushes to main / master and on pull requests (Ruby 3.3.4 and 3.2.0).
• Release — .github/workflows/release.yml runs on tags v*. It checks that the tag matches OllamaAgent::VERSION in lib/ollama_agent/version.rb, builds with gem build ollama_agent.gemspec, and pushes to RubyGems.

Repository secrets (Settings → Secrets and variables → Actions):

Release steps:

1. Bump OllamaAgent::VERSION in lib/ollama_agent/version.rb and commit to main.
2. Tag: git tag v0.1.0 (must match the version string) and git push origin v0.1.0.

MIT. See LICENSE.txt.