Crush + Ollama: Charm's Terminal Coding Agent on Local Models

Short answer: install Crush (brew install charmbracelet/tap/crush or npm install -g @charmland/crush), then put two lines in a crushrc file: provider add ollama --type ollama --base-url "http://localhost:11434/v1/" — Crush auto-discovers every model you have pulled, no API key, no JSON. Best local models: qwen3-coder:30b (19GB download, 256K context) on 24GB VRAM, or devstral:24b (14GB, 128K) on a 16GB card. And before you blame the model for ignoring its tools, raise Ollama's 4,096-token default context: OLLAMA_CONTEXT_LENGTH=65536.

One thing before anything else: if the config you found on Google or in a GitHub issue is a crush.json with a providers object, it is the old format. Crush v0.88.0 (July 31, 2026) replaced JSON config with a Bash-based crushrc, and the project's own docs now call JSON deprecated. That change is recent enough that half the setup threads out there quietly stopped matching the tool — and why this guide exists. Everything below was verified against the official Crush README, release notes, and docs in early August 2026.

---

What Crush Is

Crush is Charm's terminal AI coding agent — ~27.1K GitHub stars as of August 5, 2026, from the studio behind Bubble Tea and Glow — and local models are a first-class provider type, not a workaround. Tagline, verbatim from the repo: "Your new coding bestie, now available in your favourite terminal."

If you have used Claude Code or OpenCode, the loop is familiar: describe a task in a TUI, and the agent plans, reads files, edits them, and runs commands, with permission prompts between you and anything destructive. What Crush adds is the Charm signature — the interface is genuinely the nicest-looking thing in the category — plus a few structural choices that matter:

• LSP-enhanced context. Crush runs language servers (lsp add go --command "gopls") and feeds their understanding of your code to the model — the same context source your editor uses.
• MCP support over stdio, http, and sse transports, including OAuth for hosted servers — so the same MCP tool servers you would give any local agent plug straight in.
• Session-based work with the ability to switch models mid-session while preserving context.
• Runs everywhere — macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, NetBSD, even Android, per the README.

One honesty note before the pitch gets too warm: Crush is licensed FSL-1.1-MIT — source-available, free to use and modify, but not OSI open source the way OpenCode's MIT license is. The restriction targets competitors, not users, and each release converts to MIT after two years. For running it against your own Ollama server, it changes nothing; if license purity matters to you, now you know.

The local angle is the point of this page: pointed at Ollama, the entire stack — agent, models, tokens — costs $0, and inference traffic never leaves localhost.

---

The Config Change That Broke Every Tutorial

As of v0.88.0 (July 31, 2026), Crush is configured with a crushrc file — Bash with Crush-specific builtins — and the old crush.json format is deprecated. The docs are blunt about it: JSON still works for now, but "it won't be receiving new features."

This matters because Crush is young and moving fast (v0.86, v0.87, and v0.88 all shipped within eleven days in late July 2026), and the internet's collective memory is full of the old format. The GitHub issues about connecting Ollama, the Reddit threads, most blog tutorials — they show "providers": { "ollama": { "type": "openai", ... } } JSON. That is the legacy path now.

A crushrc is exactly what it sounds like — a .bashrc for your agent. Because Crush ships a built-in Bash interpreter, the same file works identically on Windows. Crush loads the first one it finds, in this order:

Project-local config beats global, so you can pin different models per repo. And because it is Bash, config can branch — the README's own example wraps machine-specific settings in an if [[ $HOSTNAME == ... ]] block. For a local-AI setup that is genuinely useful: one global crushrc that points at localhost on your GPU box and at a LAN IP everywhere else.

---

The Two-Minute Setup

Install Crush, pull a tool-capable model, add one provider add line. Auto-discovery does the rest.

Step 1 — Ollama and a model. If Ollama is not installed yet, start with our complete Ollama guide; the short version:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3-coder:30b   # or devstral:24b on a 16GB card

Step 2 — Install Crush. Package managers, straight from the README:

# macOS / Linux
brew install charmbracelet/tap/crush

# Any platform with Node
npm install -g @charmland/crush

# Windows
winget install charmbracelet.crush

# Or with Go
go install github.com/charmbracelet/crush@latest

Arch (yay -S crush-bin), Nix, Scoop, FreeBSD pkg, and apt/yum repos are also covered upstream.

Step 3 — Point Crush at Ollama. Create ~/.config/crush/crushrc (global) or ./.crushrc (per-project):

# crushrc
provider add ollama \
  --name Ollama \
  --type ollama \
  --base-url "http://localhost:11434/v1/"

That is the entire provider config. Note what is absent: no API key (local providers need none) and no model list — with --type ollama and an empty model list, Crush queries the server and populates models automatically. The same pattern works for the other local backends: --type lmstudio for LM Studio, --type llamacpp for a running llama-server (the README's example uses --base-url "http://localhost:2222"), plus omlx and litellm.

Now run crush in a project directory, press ctrl+l to open the model picker, and your Ollama models are in the list. Give it something real but scoped — "add input validation to the register endpoint and run the tests" — and approve its tool calls as they come. If the model narrates instead of acting, do not switch models yet: the next section is the actual fix.

Two quality-of-life builtins worth knowing from day one: permissions allow view ls grep edit skips prompts for read-mostly tools (there is also a --yolo flag that skips all prompts — the README says "be very, very careful," and so do we), and crush logs --follow tails the agent's log at ./.crush/logs/crush.log, which is where every mystery failure stops being a mystery.

---

Fixing Tool Calling (the #1828 Trap)

The most-reported Crush + Ollama failure: the model discusses what it would do but never executes a tool. The cause is almost never Crush — it is Ollama's 4,096-token default context silently truncating the tool schemas. Fix it with OLLAMA_CONTEXT_LENGTH=65536 (or higher) on the Ollama server.

Crush discussion #1828 is the canonical thread, and its shape is instructive. Users reported devstral (24B) and qwen3-coder (30B) — both built and documented for agentic tool use — responding conversationally in Crush while refusing to touch ls, write, or bash. The confusing part: the same models called tools fine when driven directly via curl, and worked when routed through Ollama Cloud instead of the local server. So Crush was fine, the models were fine, and the cloud was fine. What was different locally?

The context window. A Crush turn is not just your prompt — it is the system prompt, the schemas for every enabled tool, LSP context, file contents, and conversation history. Ollama's server defaults to a 4,096-token window (per its FAQ) regardless of what the model supports, and when the payload overflows, it truncates from the top without an error. The first thing to die is the tool instructions. The model never saw them. It is not being dumb; it is being starved — and because Crush's auto-discovery happily reports the model's native window (256K for qwen3-coder), nothing in the UI hints that the server is serving 4K.

The fix confirmed in that discussion is one environment variable on the Ollama side:

# Linux (systemd): add to the ollama service, then restart
Environment="OLLAMA_CONTEXT_LENGTH=65536"

# Or anywhere, for a foreground server
OLLAMA_CONTEXT_LENGTH=65536 ollama serve

(On a Mac menu-bar install, quit Ollama and relaunch it from a terminal with the variable set, or use launchctl setenv.) Users in the thread went as high as 128K; 64K is the sane default if your VRAM allows, and 32K is a workable floor. Remember the trade: a bigger window means a bigger KV cache in VRAM, which the next section budgets for. OLLAMA_FLASH_ATTENTION=1 and OLLAMA_KV_CACHE_TYPE=q8_0 — both from Ollama's FAQ — claw back real headroom at large contexts.

If tool calls are still flaky after the context fix, two more levers, in order:

1. Shrink the toolset. Small models degrade as the number of tool schemas grows — a pattern we also documented with Goose on local models. Crush can hide tools from the agent entirely: permissions deny sourcegraph (and any MCP tools you do not need) makes the prompt smaller and the calling task easier.
2. Register the model manually with an explicit window. User-defined entries take precedence over discovered ones, so you can pin exactly what the server actually serves: model add ollama/qwen3-coder:30b --name "Qwen3 Coder 30B" --context-window 65536 --default-max-tokens 20000 — add --discover-models true on the provider line to keep discovery for everything else.

---

Which Local Models Work

Crush needs a model that does two hard things at once: emit clean structured tool calls, and stay coherent over a long agent context. As of August 2026 the local shortlist is qwen3-coder:30b first, devstral:24b for 16GB cards, qwen3:8b only for small scoped tasks.

Specs from each model's Ollama library page, checked August 2026:

qwen3-coder:30b is the default for the same reason it is everywhere in the local-agent world right now: a mixture-of-experts design with a small active-parameter count, trained specifically for agentic coding, with a native window that laughs at the 64K you just configured. Our Qwen3 Coder guide covers the family in depth.

devstral:24b is the honest 16GB answer. Mistral built it with All Hands AI for software-engineering agents — exploring codebases, multi-file edits, tool use — and at a 14GB download it is the strongest agentic coder that fits a 16GB card. It is also one of the models users specifically could not get calling tools in discussion #1828 before the context fix, which tells you the failure was never about model quality — see our Devstral deep-dive for what it does when properly fed.

qwen3:8b is the floor, stated plainly. It supports tool calling and fits almost anywhere, but small dense models fumble multi-step tool sequences — they mis-format a call, loop, or drift into prose. Fine for "rename this function and update the imports"; frustrating for anything with branches. Our best Ollama models for tool calling roundup ranks the wider field if you want to go off-list.

---

What Your GPU Can Run

Budget past the download number, not up to it: the weights are roughly the download size in VRAM, and the 64K context you configured adds a KV cache on top.

We are deliberately not printing tokens-per-second numbers we have not measured on named hardware — throughput swings wildly with quantization, context fill, and offload ratio, and made-up benchmarks are how tutorials rot. The rule that holds everywhere: if generation suddenly crawls, you have overflowed VRAM into system RAM without noticing. Shrink the context or quantize the KV cache before shopping for a new GPU.

---

Crush vs OpenCode vs Goose

Crush is the polish pick, OpenCode is the ecosystem pick, Goose is the MCP-native autonomy pick. All three speak Ollama; none of them escapes the local tool-calling physics above.

The star gap is real and worth saying without flinching: OpenCode's community is roughly seven times larger, and community size predicts how fast your weird edge case gets fixed. What Crush has that the others do not is the Charm ecosystem — the TUI craft is a genuine daily-use difference, the LSP integration gives the model editor-grade code context, and Bash-scriptable config is quietly excellent for people managing several machines. (The two projects also share some tangled 2025 family history, but what matters for choosing today is license, ecosystem, and feel.)

Goose sits slightly apart: it is an MCP-native general agent that happens to code, rather than a coding tool that supports MCP — our Goose + Ollama guide makes the direct comparison. (Pointing Anthropic's own Claude Code at local models is also possible; that is its own guide, linked below.)

Try-them-all is a legitimate strategy here. All three are free to run locally, and the Ollama server you configured in this guide serves whichever agent is talking to it.

---

Honest Limitations

A local Crush setup is genuinely good at scoped, verifiable tasks and clearly worse than frontier models at large entangled refactors. Two Crush-specific caveats come on top.

First, the general local-agent truths, which match everything we have measured and read across this cluster:

• Scoped tasks work. "Fix this failing test," "add retry logic to this client," "write tests for this module" — a well-fed qwen3-coder-class model handles these reliably, privately, for $0.
• Long-horizon work favors the frontier. Multi-file refactors with entangled dependencies are where 30B-class models lose the thread. That gap is real in August 2026, whatever a YouTube thumbnail told you.
• Small models guess confidently. Below ~14B, expect mis-formatted tool calls and loops on anything with branches.

Now the Crush-specific ones:

• Schema churn is live, right now. The crushrc system this guide documents shipped July 31, 2026. The JSON format is deprecated but still accepted, the docs are actively evolving, and a v0.x project from a team this productive will keep moving. If a command here errors, check the README first — it will be ahead of every tutorial on the internet, including this one. We re-verify this page quarterly.
• The auto-discovery mirage. Because Crush discovers models and their native context windows automatically, the UI can honestly believe it has 256K to work with while your Ollama server silently serves 4K. Until you have set OLLAMA_CONTEXT_LENGTH yourself, assume any weird agent behavior is the context trap from the #1828 section.
• Provider auto-updates phone home. Crush refreshes its provider database from Catwalk by default. Harmless for most people; for a fully air-gapped box, set CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1 or option provider-auto-update false in your crushrc — both documented upstream.

The setup that earns its keep: Crush + qwen3-coder:30b for the daily stream of scoped, private work, and a frontier model reserved for the tasks that genuinely need one. The daily stream costing $0 forever is the point.

---

Sources

• Crush GitHub repository — star count, FSL-1.1-MIT license, install commands, crushrc config, local provider types and auto-discovery (checked August 5, 2026)
• Crush releases — v0.88.0 ".crushrc is here!" (July 31, 2026), v0.87.0, v0.86.0
• Crush config docs — JSON format deprecation notice
• Crush discussion #1828 — the local tool-calling failure reports, the Ollama Cloud control case, and the OLLAMA_CONTEXT_LENGTH fix
• Ollama FAQ — 4,096-token default context, OLLAMA_CONTEXT_LENGTH, flash attention, KV-cache quantization
• qwen3-coder, devstral, and qwen3 Ollama model cards — tags, download sizes, context windows, tool support
• OpenCode GitHub repository — star count for the comparison (checked August 5, 2026)

---

FAQ