🤖 feat: add Ollama local model support

[ThomasK33]

Summary

Adds first-class Ollama support to cmux, enabling users to run local LLMs (e.g., ollama:llama3.2, ollama:qwen2.5-coder) with full integration into cmux's agent workflow including streaming, tool calling, and reasoning.

Implementation

Core Integration

• Model string parsing - Handles Ollama model IDs with colons (e.g., ollama:gpt-oss:20b)
  • Splits only on first colon to preserve model ID format
  • Returns clear error messages for invalid formats
• Ollama provider - Uses ollama-ai-provider-v2 from Vercel AI SDK
  • Lazy-loaded to avoid startup penalty
  • Configured with compatibility: "strict" for better API compatibility
  • Respects baseURL from config (http://localhost:11434/api)
• Stream management - Full support for Ollama's streaming responses
  • Text deltas, reasoning tokens, tool calls
  • Proper stream-end event emission with usage metadata

Configuration

• Config template - Ollama section in providers.jsonc template
  • Default baseURL: http://localhost:11434/api
  • Extensible for custom Ollama endpoints
• Documentation - Updated model configuration docs
  • Examples for common Ollama models
  • baseURL configuration instructions

Testing

✅ 4 integration tests (102s total runtime):

• Basic message streaming with Ollama
• Tool calling (bash tool)
• File operations (file_read tool)
• Error handling (server not running)

✅ 964 unit tests pass
✅ All CI checks pass

Bug Fixes Applied During Development

Model parsing:

• Fixed split(":") breaking on model IDs with multiple colons
• Now uses indexOf() + slice() for first-colon split only

Test assertions:

• Fixed tests calling .join("") on event objects instead of delta text
• Updated to use extractTextFromEvents() helper

Test timing:

• Removed test.concurrent() to prevent race conditions
• Sequential execution resolves stream-end event collection issues

Configuration:

• Ensured /api suffix on baseURL in all locations:
  • Test setup, config template, docs, CI environment

How to Use

1. Install Ollama locally: https://ollama.com/download
2. Pull a model: ollama pull llama3.2
3. Configure cmux in ~/.cmux/providers.jsonc:

{
  "providers": {
    "ollama": {
      "type": "ollama",
      "baseUrl": "http://localhost:11434/api"
    }
  },
  "models": {
    "ollama:llama3.2": {
      "providerName": "ollama",
      "modelId": "llama3.2"
    }
  }
}

4. Select model in cmux: Choose ollama:llama3.2 from model picker
5. Start chatting - Full tool calling and reasoning support works automatically

Breaking Changes

None - additive only. Existing providers unchanged.

Future Enhancements (Separate PRs)

• Auto-detect Ollama server and installed models
• Pull models from UI with progress indicator
• Ollama-specific settings panel
• Health check UI for server status

---

Generated with cmux

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ammar-agent]

✅ Refactoring Complete: Test-Initiated Model Pulls

Successfully refactored Ollama setup to improve parallelism by moving model pulls from the setup action into the test suite itself.

Changes in ab90e9b

Setup Action (.github/actions/setup-ollama/action.yml)

• ❌ Removed model input parameter
• ❌ Removed sequential model pull logic
• ✅ Simplified cache key to ollama-models-v2 (model-agnostic)
• ✅ Binary cache: still works (~1.4 GB, 3s restore)
• ✅ Model cache: now shared across all models

Integration Tests (tests/ipcMain/ollama.test.ts)

• ✅ Added ensureOllamaModel() helper function
  • Checks if model exists via ollama list
  • Pulls only if needed (idempotent)
  • Multiple tests can call safely - Ollama handles deduplication
• ✅ Called in beforeAll hook before tests run
• ✅ Bumped timeout to 150s to accommodate potential model pull

Benefits

1. Better parallelism - Multiple test jobs can now share the cached model directory
2. Idempotent pulls - Tests check if model exists before pulling
3. Ollama-native deduplication - If multiple processes try to pull, Ollama handles it
4. Simplified setup action - No longer needs to know about specific models
5. Shared cache - All models go into one cache key, improving cache efficiency

Test Results (Run 19199669727)

✅ Binary cache hit - 1.4 GB restored in ~3s
✅ Model pull during test - 13 GB gpt-oss:20b pulled successfully
✅ All Ollama tests passed - 4/4 tests in 134s
✅ All CI checks passed - Static checks, unit tests, integration tests, E2E tests

Performance

First run (cold cache):

• Binary cache: hit ⚡
• Model cache: miss (expected with new cache key)
• Model pull: ~35s during test
• Total setup: ~40s (including test overhead)

Subsequent runs (warm cache):

• Will hit both binary and model cache
• ensureOllamaModel() detects model exists: ~1s
• Expected setup: <5s ⚡

Generated with cmux