ChatOllama

ChatOllama is an open-source agentic app for running AI agents with hosted or local models. The primary user entry point today is the installable chatollama-agent command-line app.

Requires Node.js 24 or newer.

npm install --global chatollama-agent
chatollama-agent

Set the API key for any provider you want to use before starting the CLI. These are the provider credentials recognized by the current release:

For example:

export OPENAI_API_KEY='replace-with-your-key'
chatollama-agent

The CLI also recognizes these explicit startup overrides:

Use provider and model overrides together when you want a specific startup model:

AGENT_PROVIDER=openai AGENT_MODEL=gpt-5-mini chatollama-agent

AGENT_PROVIDER or AGENT_MODEL takes precedence over a saved selection. AGENT_BASE_URL and AGENT_API_KEY override its endpoint and credential without changing its provider/model identity. A mapped provider credential is still required to add that provider's built-in models to automatic discovery; AGENT_API_KEY alone does not do so.

Compatibility note: Ollama is supported as one OpenAI-compatible provider alongside the providers above. The CLI still falls back to ollama/qwen3:8b when no model is available, and AGENT_MODEL without AGENT_PROVIDER uses Ollama. This keeps the command loop available but does not mean that model is installed or reachable. To select it explicitly, set AGENT_PROVIDER=ollama and, when needed, AGENT_BASE_URL.

On startup, ChatOllama discovers available models. Configured remote providers contribute a built-in model catalog; OpenAI also performs filtered model discovery, and an available Ollama endpoint contributes its installed models. Discovery failures produce warnings without preventing the CLI from opening.

At the prompt:

• Enter a message and press Return. Follow-up messages continue the same in-memory conversation.
• The Runtime may call read_file, list_directory, grep, and find_files to inspect the directory where the CLI was started. Both terminal modes show each tool's validated input, execution status, and bounded result.
• Enter /models to view available models and choose one. In an interactive terminal, use the arrow keys and Return; press Escape to cancel.
• Enter /model <provider>/<model-id> to switch directly, for example /model openrouter/openai/gpt-5-mini. The model must appear in /models.
• Enter /new to clear conversation history while keeping the selected model.
• Press Ctrl+C during a response to cancel that response and keep the CLI open. Press Ctrl+C while idle to quit.
• Enter /exit to quit cleanly.

A successful model selection applies to later messages and is saved as the next startup default. Conversations and API keys are not saved.

For plain or scripted input, /models prints a numbered list instead of the interactive picker:

printf '/models\n/exit\n' | chatollama-agent

To run a deterministic tool loop without a provider, network request, or paid API key:

pnpm install --frozen-lockfile
pnpm agent:tool-loop-demo

The demo performs two real model steps with AI SDK MockLanguageModelV3: the first requests the safe UTC-time tool, and the second receives its result and streams the final answer.

To exercise all six workspace tools without a provider or network request:

pnpm agent:workspace-tools-demo

The CLI startup directory is the workspace root. Tool paths must be relative to that root; absolute paths, .. escapes, prefix-confusion paths, and symlinks that resolve outside it are rejected. Read/search results are capped and report truncation. write_file and exact edit_file use atomic replacement, serialize changes to the same path, and reject content over 1,048,576 bytes. Successful read_file, write_file, and edit_file results include a complete-content sha256:<hex> version. write_file and edit_file accept an optional expectedVersion; a stale value returns VERSION_CONFLICT without changing the file. edit_file supports the legacy single exact replacement and batches of up to 100 replacements: every literal oldText must match exactly once in the original content, ranges must be non-overlapping, and the whole batch is atomic. The cumulative edit input and resulting content are each limited to 1,048,576 UTF-8 bytes; matching is never fuzzy. They do not expose shell commands.

For configuration precedence, saved preference locations, plain-mode behavior, and provider-specific examples, see the Agent CLI guide.

ChatOllama is an app for running AI agents, not an SDK for building them.

MIT License

This README should be updated with every release that changes user-visible behavior.