ChatOllama: a terminal agent that reads your working directory
ChatOllama is an open source agentic app for running AI agents across local and hosted models.
At a glance
- What is it?
- ChatOllama is an open source agentic CLI from sugarforever that runs tool-calling agents against hosted or local models. Its workspace tools are read-only and sandboxed to the directory you launch it from, which is the most interesting and most limiting thing about it.
- Who is it for?
- Adopt ChatOllama if you want a terminal agent that can inspect a repository without being able to write to it, and you are comfortable setting provider keys as environment variables. Skip it if you need an agent that edits files or runs commands, because the workspace tools are read-only by design and there is no write or shell surface to enable.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem ChatOllama solves, and who it is aimed at
Most coding agents want to write to your repository. ChatOllama takes the opposite position. The README describes it as an app for running AI agents, not an SDK for building them, and the primary entry point is an installable command called chatollama-agent. You start it in a directory, ask a question, and the runtime may call read_file, list_directory, grep and find_files to inspect that directory. Nothing in the documented tool set writes a file or spawns a shell command. The README says this plainly: workspace tools are read-only, they do not expose writes or shell commands. That single design decision defines the audience. It suits someone who wants a second pair of eyes over a codebase, a log directory, or a documentation tree, and who does not want an agent holding a write handle. It also suits people who want to point the same CLI at a hosted model or at a local Ollama endpoint without changing tools. It does not suit anyone expecting an agent that fixes the bug it just found.
Provider selection is environment variables, not a config file
Configuration lives in the environment. The README lists the recognized credentials: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY (falling back 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 string ollama. Four startup overrides sit on top: AGENT_PROVIDER selects one of openai, anthropic, google, deepseek, openrouter or ollama; AGENT_MODEL selects the model ID; AGENT_BASE_URL overrides the endpoint; AGENT_API_KEY overrides the credential. AGENT_MAX_STEPS takes a positive integer and defaults to 4. The README gives this example: AGENT_PROVIDER=openai AGENT_MODEL=gpt-5-mini chatollama-agent. The precedence rules are worth reading closely. AGENT_PROVIDER or AGENT_MODEL takes precedence over a saved selection, while AGENT_BASE_URL and AGENT_API_KEY override the endpoint and credential without changing the provider or model identity. There is a subtlety the README flags directly: a mapped provider credential is still required to add that provider's built-in models to automatic discovery, so AGENT_API_KEY alone will not do it. If you plan to use /model to switch providers mid-session, set the real credential variables, not just the override.
How model discovery and the step budget work
On startup the CLI discovers models. Configured remote providers contribute a built-in catalog, OpenAI additionally performs filtered model discovery, and a reachable Ollama endpoint contributes its installed models. Discovery failures produce warnings rather than blocking startup, which is a reasonable choice for a tool that may run offline. The README notes a compatibility fallback: when no model is available the CLI falls back to ollama/qwen3:8b, and AGENT_MODEL without AGENT_PROVIDER uses Ollama. The README is explicit that this keeps the command loop available but does not mean the model is installed or reachable, so a fallback can look like a working session right up to the first failed response. The step budget is the other mechanism to understand. AGENT_MAX_STEPS defaults to 4, and it caps how many model steps a single prompt may take. Four steps is enough for a read, a grep and a summary. It is not enough for a long exploratory loop over a large tree, and the README does not describe what happens when the budget is exhausted, so raising it is something you would have to test rather than read about.
The workspace sandbox is the real feature, and the real limit
The CLI startup directory becomes the workspace root. Tool paths must be relative to that root. The README states that absolute paths, .. escapes, prefix-confusion paths, and symlinks resolving outside the root are rejected, and that results are capped and report truncation. This is a stricter containment story than most terminal agents offer, and it is enforced at the argument level rather than by asking the model nicely. Two consequences follow. First, the sandbox is per-invocation: start the CLI in the wrong directory and the agent sees a different project. Second, prefix-confusion and symlink rejection mean some legitimate access patterns will fail, and the README does not document an allowlist or an escape hatch. If your repository is assembled from symlinked subtrees, expect the tools to refuse paths a human would consider inside the project. The bounded result sizes are also undocumented in the README, so the truncation threshold is something you discover by hitting it.
Running it, and the two demos that need no provider
Installation is two commands: npm install --global chatollama-agent, then chatollama-agent. Node.js 24 or newer is required. For scripted use, the README shows piping input: printf '/models\n/exit\n' | chatollama-agent, which prints a numbered model list instead of the interactive picker. In-session commands are /models to view and choose a model, /model <provider>/<model-id> to switch directly (the README's example is /model openrouter/openai/gpt-5-mini, and the model must appear in /models), /new to clear history while keeping the model, and /exit to quit. Ctrl+C cancels a response while it is streaming and quits when idle. Two demo scripts are worth knowing because they avoid both network calls and paid keys. pnpm agent:tool-loop-demo performs two real model steps using the AI SDK MockLanguageModelV3: the first requests a safe UTC-time tool, the second receives the result and streams a final answer. pnpm agent:workspace-tools-demo exercises all four workspace tools without a provider. Both are preceded by pnpm install --frozen-lockfile. These are the fastest way to confirm the tool loop works before you spend anything on tokens.
State, persistence and what is not saved
The persistence model is deliberately thin. Follow-up messages continue the same in-memory conversation, and /new clears that history. A successful model selection applies to later messages and is saved as the next startup default. Conversations and API keys are not saved. That is a clear boundary and it cuts both ways. You get no accidental credential files on disk, and you also get no session resume: close the terminal and the context is gone. If your workflow depends on resuming a long investigation tomorrow, this CLI does not support it, and the README offers no export or transcript command. The saved model preference is the only thing that survives, which means a startup override you set once for a test will silently become the default for the next session unless you change it back.
Where it fits against editor-integrated agents
The obvious comparison is an editor-integrated agent such as Cursor or the agent mode in VS Code. Those tools also read and grep your project, but they sit inside the editor, hold a write handle on the buffer, and apply edits with a diff you review. ChatOllama has no editor, no diff, and no write path. The difference is not polish, it is capability: an editor agent can close the loop between finding a problem and fixing it, and ChatOllama stops at finding. That makes it a worse tool for refactoring and a better one for auditing, because the blast radius of a wrong tool call is a read rather than a modified file. The other comparison is the AI SDK itself. The README's own framing separates the two: ChatOllama is an app for running agents, not an SDK for building them. If you want custom tools, a write path, or your own orchestration, you are looking at the wrong layer and should be building on the SDK the demos already use.
Maintenance, licensing and what to verify first
The repository is active, with agent-v0.4.0 and agent-v0.3.0 released on consecutive days in September 2026, and the README carries a note that it should be updated with every release that changes user-visible behavior. That note is a maintenance commitment on paper; whether it holds is something you can check by diffing the README between two release tags. The licence is the item that needs attention before adoption. The README links to an MIT License file, but the repository metadata reports NOASSERTION, which usually means the licence could not be identified automatically. Those two signals disagree, and only the LICENSE file in the repository settles it. Read that file rather than either summary; this is a factual discrepancy, not a legal opinion. Upgrade cost is low in the documented surface: the CLI is installed globally through npm, configuration is environment variables rather than a config file, and no conversation state is persisted, so there is no migration step for saved data. The thing to verify first is the sandbox, not the model list. Run pnpm agent:workspace-tools-demo, then start the CLI in a directory containing a symlink that points outside the tree and confirm the rejection behaviour matches the README. If it does, you know the containment claim is real before you point the agent at anything that matters.
Editorial conclusion
Adopt ChatOllama if you want a terminal agent that can inspect a repository without being able to write to it, and you are comfortable setting provider keys as environment variables. Skip it if you need an agent that edits files or runs commands, because the workspace tools are read-only by design and there is no write or shell surface to enable. Before trusting it, check the LICENSE file directly, since the repository metadata reports NOASSERTION while the README states MIT, and run pnpm agent:workspace-tools-demo to see exactly which paths the sandbox rejects.
Community notes