# ChatOllama: an agentic CLI for local and hosted models > ChatOllama ships an installable chatollama-agent command that runs a bounded tool loop over local Ollama models or hosted providers. The README is clear about what it is and unusually clear about what it is not. **sugarforever/chat-ollama** — ChatOllama is an open source agentic app for running AI agents across local and hosted models. - Repository: https://github.com/sugarforever/chat-ollama - Website: https://chatollama.cloud - Stars: 3,514 · Forks: 561 - Language: TypeScript - License: NOASSERTION - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/sugarforever-chat-ollama ## The problem ChatOllama solves, and who it is for Most chat front ends for local models stop at a text box. You type, the model answers, and nothing else happens. ChatOllama's current entry point, the chatollama-agent command, is built around the opposite assumption: that the model should be able to inspect the directory you started it in before it answers. The README lists four tools the Runtime may call, read_file, list_directory, grep, and find_files, and notes that both terminal modes show each tool's validated input, execution status, and bounded result. That visibility is the point. You are not asked to trust that the agent read the right file; the CLI shows you what it asked for and what came back. The audience is narrower than the project name suggests. This is for engineers who already have a model endpoint, either a hosted key or an Ollama instance, and who want a conversational agent in the terminal rather than a web UI or a Python class. It is not aimed at people building agent frameworks. The README ends with a sentence that forecloses that use case directly: ChatOllama is an app for running AI agents, not an SDK for building them. If you arrived looking for a library to embed in your own service, the README is telling you to look elsewhere. ## How the agent loop is bounded and sandboxed The mechanism that matters most here is the step budget. AGENT_MAX_STEPS sets a positive-integer limit on how many steps each prompt may take, and the default is 4. That default is low. A question that needs to read three files and then summarize will spend its budget quickly, and the README does not describe what happens when the budget is exhausted, only that the variable sets the ceiling. Raising it is a one-variable change, but you should know that you are trading latency and token spend for depth. The workspace boundary is the second mechanism. The CLI startup directory is the workspace root. Tool paths must be relative to that root, and absolute paths, .. escapes, prefix-confusion paths, and symlinks that resolve outside it are rejected. This is a real constraint rather than a disclaimer, and it means the agent's reach is exactly the directory you chose when you ran the command. Results are capped and report truncation, so a grep across a large tree will tell you it was truncated rather than silently returning a partial answer. The tools are read-only by design: no writes, no shell commands. That removes a whole class of failure modes, and it also removes a whole class of tasks. Model discovery is the third piece. On startup the CLI discovers available models. Configured remote providers contribute a built-in 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, which is a sensible choice for a terminal tool but means a misconfigured provider can look like an empty model list rather than an error. ## Installing chatollama-agent and running a first prompt The README gives a two-line install. Node.js 24 or newer is required, and the package is installed globally. ```bash npm install --global chatollama-agent chatollama-agent ``` Before the CLI can talk to a hosted provider you need that provider's credential in the environment. The README lists the recognized names, including OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY with a fallback to GOOGLE_GENERATIVE_AI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, and OLLAMA_API_KEY, which is optional and defaults to the non-secret value ollama. ```bash export OPENAI_API_KEY='replace-with-your-key' chatollama-agent ``` If you want a specific provider and model at startup rather than picking from a menu, the README documents explicit overrides. AGENT_PROVIDER accepts openai, anthropic, google, deepseek, openrouter, or ollama, and AGENT_MODEL selects the model ID. ```bash AGENT_PROVIDER=openai AGENT_MODEL=gpt-5-mini chatollama-agent ``` Inside the prompt, /models opens a picker. In an interactive terminal you move with the arrow keys and confirm with Return; Escape cancels. /model takes a direct switch in provider/model-id form, for example /model openrouter/openai/gpt-5-mini, and the README notes the model must appear in /models for that to work. /new clears the conversation while keeping the selected model, and /exit quits 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 scripted use the picker degrades to plain output, which is what makes the CLI usable in a pipeline. ```bash printf '/models\n/exit\n' | chatollama-agent ``` If you would rather see the loop work before spending money on tokens, the repository ships a demo that runs without a provider, network request, or paid API key. It performs two real model steps with AI SDK MockLanguageModelV3: the first requests the safe UTC-time tool, the second receives its result and streams the final answer. ```bash pnpm install --frozen-lockfile pnpm agent:tool-loop-demo ``` There is a second demo, pnpm agent:workspace-tools-demo, that exercises all four workspace tools without a provider or network request. ## Where the CLI falls short The Ollama fallback deserves scrutiny. The README states that the CLI falls back to ollama/qwen3:8b when no model is available, and that AGENT_MODEL without AGENT_PROVIDER uses Ollama. It then adds a caution that is easy to skim past: this keeps the command loop available but does not mean that model is installed or reachable. In practice a fresh install with no keys can start, accept a prompt, and fail at the model call. The README does not document error handling for that path, so you should treat the fallback as a convenience rather than a working default. Provider credentials have a similar edge. 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. So if you set AGENT_API_KEY expecting the model list to fill in, it will not. AGENT_BASE_URL and AGENT_API_KEY override the selected provider's endpoint and credential without changing its provider or model identity, which is a deliberate separation but one that surprises people who expect a key to imply a provider. The read-only tool set is the largest limitation and it is intentional. An agent that cannot write files or run shell commands cannot refactor a module, apply a patch, or run your test suite. For those tasks this is the wrong tool, and no amount of configuration changes that. Persistence is the other gap: conversations and API keys are not saved, so every session starts empty and you re-export your credential each time. The README does not document rollback or history recovery, because there is no history to recover. ## ChatOllama versus a plain Ollama chat client The obvious comparison is a plain Ollama chat client, the kind of tool that streams completions from a local model and nothing more. The difference is not the model access, since ChatOllama supports Ollama as one OpenAI-compatible provider alongside the hosted ones. The difference is what happens between your prompt and the answer. A plain client sends your text to the model and prints the stream. ChatOllama runs a step loop in which the model can request read_file, list_directory, grep, or find_files, receive a bounded result, and continue, up to AGENT_MAX_STEPS steps, with each tool call's input and status shown in the terminal. That also means ChatOllama inherits costs a plain client does not have. A single question can consume several model calls, so token spend and latency are multiples of a direct completion, and the step budget is the only brake. A plain client has no such multiplier. If your questions are answerable from the prompt alone, the agent loop is overhead. If your questions are about a codebase, the loop is the entire value. The repository also contains a Nuxt web application with Prisma, Postgres, ChromaDB, and Redis wiring in docker-compose.yaml, and the README points to packages/agent-cli/README.md for configuration precedence and saved preference locations. That web app is a different product surface from the CLI, and the README does not present them as interchangeable. ## Maintenance cadence, licence, and upgrade cost The repository is not archived, and the last push was on 2026-09-10. Two agent releases landed on 2026-09-09: agent-v0.3.0 and agent-v0.4.0. That is a tight release window, and the README carries an instruction to itself that is worth noting: this README should be updated with every release that changes user-visible behavior. Whether that has held for every release cannot be confirmed from what the repository states. Upgrading the CLI is a global npm install, so the cost is mostly in re-reading the provider and override tables when a release changes them. The environment-variable surface is broad, which is where upgrade friction tends to appear: AGENT_PROVIDER, AGENT_MODEL, AGENT_BASE_URL, AGENT_API_KEY, and AGENT_MAX_STEPS are all startup overrides, and the README notes that AGENT_PROVIDER or AGENT_MODEL takes precedence over a saved selection. If you pin a model in a shell profile, a saved selection will not override it, which is the intended behavior but easy to forget. The repository's package.json declares the MIT License, while the repository metadata reports NOASSERTION. Those two disagree, and the README links to ./LICENSE as MIT. If licence terms matter to your organization, read the LICENSE file itself rather than either summary; this is a factual discrepancy in the repository, not legal advice. The Dockerfile pins NODE_VERSION to 24.20.0, consistent with the Node.js 24 requirement for the CLI. ## Conclusion Adopt it if you want a terminal agent that can read a project directory with read_file, list_directory, grep and find_files while staying read-only, and you are willing to keep your own API keys in environment variables because the README says neither conversations nor keys are saved. Do not adopt it if you need a library to build agents on, since the README states plainly that ChatOllama is an app and not an SDK, or if you need the agent to write files or run shell commands. Before committing, verify three things yourself: the Node.js 24 requirement, which provider variable your shell actually exports, and whether the model you intend to use appears in /models. If you want the web app instead of the CLI, note that the README points at packages/agent-cli/README.md for configuration precedence and saved preference locations rather than documenting them at the top level. ## FAQ ### How do I chat with Ollama using ChatOllama? Install the CLI with npm install --global chatollama-agent and run chatollama-agent. Ollama is supported as one OpenAI-compatible provider; set AGENT_PROVIDER=ollama and, when needed, AGENT_BASE_URL to point at your endpoint. ### What is ChatOllama? It is an open source agentic app for running AI agents with hosted or local models, and the primary user entry point today is the installable chatollama-agent command-line app. The README states it is an app for running agents, not an SDK for building them. ### Does ChatOllama store your chats? The README states that conversations and API keys are not saved. A successful model selection is saved as the next startup default, but the conversation itself is in-memory and /new clears it. ## Sources - [Issues](https://github.com/sugarforever/chat-ollama/issues) - [Project website](https://chatollama.cloud) - [README](https://github.com/sugarforever/chat-ollama/blob/main/README.md) - [Releases](https://github.com/sugarforever/chat-ollama/releases) - [sugarforever/chat-ollama on GitHub](https://github.com/sugarforever/chat-ollama) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sugarforever-chat-ollama