↓ Skip to main content
9 – 17 UHR +49 8031 3508270 LUITPOLDSTR. 9, 83022 ROSENHEIM
DE / EN
Coding agent Charmbracelet, Inc. (Charm) Terminal (TUI), Headless, Client-server

Crush

Crush is Charm's AI coding agent for the terminal: free model choice, custom OpenAI and Anthropic endpoints, LSP, MCP and the FSL-1.1-MIT license.

Licence FSL-1.1-MIT (MIT after two years)
First release July 2025 (version 0.1.0)
Interfaces Terminal UI (TUI), Headless (crush run), Client-server mode with HTTP API (crush server)
Platforms macOS, Linux, Windows, Android, FreeBSD, OpenBSD, NetBSD
Instruction file AGENTS.md, CRUSH.md (also reads CLAUDE.md and GEMINI.md)

The seven building blocks in Crush

How Crush implements the building blocks of an AI harness

  1. 1

    Agent loop

    The agent loop runs interactively in the terminal UI, headless with crush run (task as an argument or through a pipe) and in client-server mode: crush server exposes an HTTP API with an OpenAPI 3.1 description through which several clients share a session.

  2. 2

    Tools and execution environment

    Built-in tools cover files (view, edit, multiedit, write), search (glob, grep), a shell with background jobs, web fetching and LSP functions such as diagnostics, references and renaming. You connect MCP servers via stdio, HTTP or SSE, with OAuth where needed.

  3. 3

    Context management

    Crush reads project rules from AGENTS.md and CRUSH.md and, per its source code, also from CLAUDE.md, GEMINI.md, .cursorrules and .github/copilot-instructions.md; crush init creates an AGENTS.md by default. Language servers add further context, and .crushignore excludes files.

  4. 4

    State and memory

    Crush stores sessions per project in an SQLite database in the .crush directory. You resume a session with --continue or --session, and crush session lists, shows and deletes them. Crush summarizes long histories automatically, and you can switch models mid-session.

  5. 5

    Permissions

    By default, Crush asks before tool calls; only provably read-only shell commands such as git status run without a prompt. permissions allow approves tools, permissions deny hides them. Yolo mode (-y) skips prompts and blocks dangerous commands, sysadmin mode (-yy) allows everything.

  6. 6

    Verification and feedback

    Per its source code, the edit tool appends the language server's diagnostics to its result after every change, so the model sees errors right away. Hooks check tool calls deterministically and can block or rewrite commands; per the documentation, their format largely matches Claude Code.

  7. 7

    Orchestration

    Since version 0.100.0 of 5 November 2026, Crush spawns subagents in the background, checks on them, sends them follow-ups, stops them or moves them to a different model. A large and a small model can be set separately.

Models and model access

Which models the harness uses and how they are obtained

Models and model access
Models No fixed default model: per the README, the quickest start is a model from Charm's Hyper inference service; alternatively you pick provider and model with ctrl+l and enter an API key
Access routes Charm Hyper, Anthropic, OpenAI, Google Gemini and Vertex AI, Amazon Bedrock (Claude), Azure OpenAI, GitHub Copilot, OpenRouter, Vercel AI Gateway, Groq, Cerebras, xAI, Z.ai, MiniMax, Moonshot, Hugging Face, Ollama, LM Studio, llama.cpp, LiteLLM, custom OpenAI or Anthropic compatible endpoints
Free choice of model Yes
Custom endpoint / LLM gateway Yes
Per the README, you add custom providers with provider add: type completions for OpenAI-compatible APIs, responses for OpenAI Responses and messages for Anthropic-compatible APIs, each with --base-url, --api-key and optionally --extra-header. The option default-providers false hides all built-in providers.
Features
MCP servers Sub-agents Hooks Skills Headless / CI Resume sessions
Running it with herdr
Supported by herdr Yes
State detection Crush itself (reports via the herdr socket)
Integration State and session ID, no resume command
The herdr documentation (version 0.9.5, retrieved on 22 November 2026) lists Crush under “Supported by the agent”. Per its source code, Crush has reported the states idle, working and blocked plus the session ID since version 0.81.0; nothing needs to be installed.
More about herdr →

Enterprise use

Data processing, controls and pricing model according to the vendor

Data processing

Crush runs locally and sends prompts, file contents and tool results to the chosen provider. For Charm's Hyper service, per its documentation, personal plans are not ZDR and allow training on prompts; team plans and prepaid credits are ZDR. With local models, prompts and code stay inside your own network.

Telemetry

Per the README, usage metrics are on by default (opt-out), pseudonymous via a device hash and without prompts or responses. Turn them off with CRUSH_DISABLE_METRICS=1, DO_NOT_TRACK=1 or option metrics false. If you use Hyper, Charm may associate the metrics with your Hyper account per the README.

License

FSL-1.1-MIT permits internal use and professional services for licensees, but prohibits commercial products or services that substitute for Crush or offer the same functionality. Each version also becomes available under MIT two years after its release. Review the license before building Crush into your own products.

Permissions

Prompting before tool calls is the default. Yolo mode blocks only a configurable list of dangerous commands, which per the source code is explicitly not a sandbox; sysadmin mode allows everything. Orca launches Crush with --yolo by default. Hooks additionally block commands deterministically.

Admin controls and pricing

No central user or role management for Crush is documented; you distribute policies through a global crushrc, which per the README runs as trusted code at startup. Crush itself is free. Per its documentation, Hyper Enterprise offers SAML SSO, per-user spend caps and audit exports.

Strengths
  • Free model choice across around 20 built-in providers, plus local models with automatic model discovery
  • Custom endpoints in OpenAI Chat Completions, OpenAI Responses or Anthropic Messages format, with custom headers
  • Tight LSP integration: diagnostics, references and renaming, with language servers set up automatically by default
  • Reports its own state to herdr without an additional integration
  • Configuration as a Bash script (crushrc) that works the same on every platform, from Windows to Android and BSD
  • Hooks largely compatible with Claude Code, plus Agent Skills, MCP with OAuth and subagents
Limitations
  • The FSL-1.1-MIT license is not an open-source license in the OSI sense; competing commercial offerings based on Crush are excluded
  • Usage metrics are on by default and must be turned off explicitly
  • No sandbox: yolo mode only blocks a command list, sysadmin mode blocks nothing
  • Still version 0.x with weekly releases; subagents only arrived in November 2026, and hooks are preliminary per the README
  • No central user, role or policy management documented
  • No desktop app and no IDE integration

Use cases

Typical tasks for this harness

Coding in the terminal with a freely chosen model and LSP-backed context
Several Crush sessions in parallel in herdr with status reporting, without extra installation
Running exclusively through a corporate gateway with the built-in providers hidden
Scripted tasks and pipes with crush run, for example in CI
Working with local models via Ollama, LM Studio or llama.cpp for confidential projects

Crush is an AI coding agent for the terminal from Charmbracelet, Inc. (Charm). As an AI harness, Crush connects a freely chosen language model to files, shell, language servers (LSP) and MCP tools and runs on macOS, Linux, Windows and BSD. Its source code is public but licensed under the source-available FSL-1.1-MIT license. As of 22 November 2026.

What is Crush?

Crush is Charm’s terminal agent for software development and adjacent tasks, written in Go and built on Charm’s own terminal libraries such as Bubble Tea. The project continues the earlier Go project opencode-ai/opencode: per its README, that archived repository points to Crush as its continuation by the original author and the Charm team. Crush is not the same as today’s OpenCode from Anomaly, a separate project written mainly in TypeScript.

Per the GitHub API, charmbracelet/crush has 29,163 stars. The first version 0.1.0 was tagged on 29 July 2025, and the current version per the releases is 0.102.0 from 19 November 2026 (as of 22 November 2026); between 29 October and 19 November 2026, a new minor version shipped every week. You install Crush with brew install charmbracelet/tap/crush, npm install -g @charmland/crush, Winget, Scoop, Charm’s package repositories for Debian and Fedora or go install, among other options. Per the README, Crush runs on macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD and NetBSD.

Is Crush open source? License and costs

Not in the sense of the Open Source Initiative. Per its LICENSE.md, Crush is licensed under the Functional Source License 1.1 with an MIT future license (FSL-1.1-MIT); GitHub does not detect this license automatically and reports NOASSERTION. The FSL permits use, modification and redistribution for any purpose other than a “Competing Use”, meaning a commercial product or service that substitutes for Crush or offers the same functionality. Internal use, non-commercial education and research, and professional services for licensees are explicitly permitted. Because the license thereby excludes certain fields of use, Crush is source-available and not open-source software under the OSI definition.

Per fsl.software, the FSL is a Fair Source license that converts to a permissive license two years after each version is released. For Crush, that is MIT: the first FSL versions from July 2025 therefore become available under MIT from July 2027. Code by the original author Kujtim Hoxha from the period up to 30 May 2025 remains under MIT per the license file. For organizations, this means: the license text explicitly permits using the agent internally, but not building your own commercial coding agent product on top of Crush. Crush itself is free; costs arise from the model providers or from Charm’s Hyper inference service.

Crush as an AI harness

Crush covers the building blocks of a harness itself and puts particular emphasis on language servers. Per the README, Crush uses LSPs as additional context, and per its configuration schema it sets up suitable language servers by default based on typical project files. Tools for diagnostics, references, definitions and renaming build on them; per the source code, the edit tool appends the language server’s diagnostics to its result after every change. Crush connects MCP servers via stdio, HTTP and SSE, with OAuth where needed. On top of that come Agent Skills following the open standard and hooks whose format, per the hooks documentation, largely matches Claude Code.

The agent loop runs interactively in the terminal UI, headless with crush run for scripts and pipes, and in client-server mode: crush server exposes an HTTP API with an OpenAPI 3.1 description, and several clients in the same directory share sessions, permissions, LSP and MCP. Crush stores sessions per project in an SQLite database under .crush; --continue or --session resume them. Since version 0.100.0 of 5 November 2026, Crush spawns subagents in the background, sends them follow-ups, stops them or moves them to a different model. You configure Crush through a crushrc, a Bash script with its own commands such as provider add, mcp add or permissions allow, which per the README works the same on every platform thanks to a built-in Bash interpreter.

Models and model access

Crush is model-agnostic. Per the README, environment variables connect around 20 providers, including Anthropic for Claude, OpenAI for GPT, Google for Gemini via the Gemini API or Vertex AI, Amazon Bedrock (currently Anthropic models only, per the README), Azure OpenAI including Entra ID, OpenRouter, Vercel AI Gateway, Groq, Cerebras and xAI. With crush login you sign in to Hyper, GitHub Copilot, OpenAI (ChatGPT) or xAI, per the CLI help. Crush detects local models from Ollama, LM Studio, llama.cpp or LiteLLM automatically. Charm maintains the model list in the open Catwalk catalog, which Crush updates online by default; you can switch models mid-session without losing context.

Per the README, the quickest start is Charm’s own Hyper inference service with open-weight models. Per the Hyper documentation on plans and billing, personal plans cost 10 to 200 US dollars per month and are not zero data retention (ZDR); team plans cost 30 to 220 US dollars per user per month and, like prepaid credits, are ZDR. Enterprise offers SAML SSO, per-user spend caps and audit exports, among other things, and lists US inference and data residency in the United States.

Custom endpoints are explicitly supported per the README on custom providers: provider add creates a provider with --base-url, --api-key and optionally --extra-header, with type completions for OpenAI-compatible APIs, responses for OpenAI Responses or messages for Anthropic-compatible APIs. With option default-providers false, Crush hides all built-in providers so that only your own endpoint remains; you then add models yourself with model add. This lets you run Crush in proxy mode through the AI Gateway, which checks permissions and budgets and assigns every token to a cost center.

Enterprise use: data protection and governance

Crush runs locally and sends prompts, file contents and tool results to the chosen model provider. Important for data protection: telemetry is on by default. Per the README on metrics, Crush records pseudonymous usage metrics tied to a device-specific hash; per the vendor, prompts and responses are never included. CRUSH_DISABLE_METRICS=1, DO_NOT_TRACK=1 or option metrics false turn this off. Crush also loads the provider list from Catwalk; option provider-auto-update false prevents this for isolated environments.

Per the README, the permission model asks before tool calls by default; only provably read-only shell commands such as git status run without a prompt. permissions allow approves individual tools, permissions deny hides them entirely. Yolo mode (-y or --yolo) skips all prompts and blocks only a list of dangerous commands such as curl, ssh, package managers or systemctl; sysadmin mode (-yy) allows everything. Per the source code, this list is a guardrail against accidents and explicitly not a sandbox. Also note: per the README, crushrc and crush.json count as trusted code and run at startup, and Crush adds an attribution trailer to the commits and pull requests it creates by default.

No central user or policy management for Crush itself is documented. You distribute policies through a global crushrc with your own provider, disabled metrics, permissions rules and hooks that block dangerous commands deterministically. Regardless of that, source code and prompts belong in your record of processing activities.

Running Crush with herdr and Orca

Crush is supported by herdr, and the support comes from the agent itself: the herdr agent list in version 0.9.5 lists Crush under “Supported by the agent”, so you do not need to install an integration. Per its source code, Crush has reported the states idle, working and blocked plus the session ID over the herdr socket since version 0.81.0 of 29 June 2026, as soon as it runs in a herdr pane. Per the source code, Crush does not currently send a command for resuming the session after a herdr server restart.

Orca lists “Charm Crush” in its own agent overview with automatic setup, without status reporting or hooks. Orca launches supported agents with their permission-bypass flag by default, which for Crush means --yolo; you can switch this default to Manual in the Orca settings.

How does Crush differ from Claude Code and OpenCode?

Crush is model-agnostic and available as source-available code, whereas Claude Code comes from the model vendor Anthropic, is proprietary and tailored to Claude models. OpenCode from Anomaly is model-agnostic as well, but licensed under MIT, written mainly in TypeScript and also offers a desktop app. Typical of Crush are its tight LSP integration, configuration as a Bash script, broad platform support down to Android and BSD, and built-in status reporting to herdr. Crush and Claude Code ask before file changes and shell commands in their default mode. If you are looking for a model-agnostic agent with a desktop app under Apache-2.0, Goose is one option.

Where it fits: developer harness and enterprise harness

Crush is a harness for developers who work in the terminal. For business users without a command line, CompanyGPT is the matching harness, with MCP tools, enterprise knowledge and roles from Entra ID or Keycloak. The AI Gateway provides the shared cost and governance layer; per the product page, its companion measures agent time for Claude Code, Codex, OpenCode, Pi, GitHub Copilot CLI and Gemini CLI, so you capture Crush through proxy mode. Our overview of AI harnesses covers further coding agents and orchestrators.

From developer harness to enterprise harness

Coding harnesses are tools for developers. Business users, cost control and governance need two more layers.

CompanyGPT – the harness for business users

CompanyGPT gives any language model tools via MCP servers, integrations and n8n, company knowledge via companyRAG, roles from Entra ID or Keycloak, and audit logs – operated in your own cloud tenant (Azure, AWS or Google Cloud) or sovereignly on STACKIT.

Discover CompanyGPT
AI Gateway – cost and governance for every agent

The AI Gateway bundles the model access of your tools and coding agents behind an OpenAI-compatible API: sign-in via Entra ID, Keycloak or Cognito, budgets and hard limits per team and user, cost attribution per project and repository via the Companion, and logging of every request.

View the AI Gateway

Frequently Asked Questions

What is Crush?

Crush is an AI coding agent for the terminal from Charmbracelet, Inc. (Charm). It connects a freely chosen language model to files, shell, language servers and MCP tools and asks before tool calls by default. Crush runs on macOS, Linux, Windows and BSD, continues the earlier Go project opencode-ai/opencode and is licensed under FSL-1.1-MIT.

Is Crush open source and free?

Free, yes; open source in the OSI sense, no. Crush is licensed under the Functional Source License FSL-1.1-MIT: internal use, modification and redistribution are permitted, but commercial offerings that compete with Crush are not. Each version also becomes available under MIT two years after its release. Costs arise from the model provider or from Charm's own Hyper inference service.

Which models does Crush support?

Crush is model-agnostic. Per the README, environment variables connect around 20 providers, including Anthropic, OpenAI, Google Gemini, Vertex AI, Amazon Bedrock for Claude, Azure OpenAI, OpenRouter, Groq and xAI, plus Charm's Hyper service. With crush login you can also use GitHub Copilot or ChatGPT. Crush detects local models from Ollama, LM Studio or llama.cpp automatically, and you can switch models mid-session.

Does Crush work with a custom endpoint or the innFactory AI Gateway?

Yes. Per the README, provider add creates custom providers with base URL, key and headers, in OpenAI Chat Completions, OpenAI Responses or Anthropic Messages format. This runs Crush in proxy mode through the AI Gateway, which checks budgets and assigns tokens to a cost center. With default-providers false you hide all other providers. The gateway companion's agent time measurement does not currently cover Crush.

Can Crush be used in a GDPR-compliant way?

That depends mainly on the model provider. Crush runs locally and stores sessions in the project directory, but by default it sends pseudonymous usage metrics without prompts to Charm; CRUSH_DISABLE_METRICS=1 turns this off. Prompts and code go to the chosen provider, which must be covered contractually. For Hyper, personal plans are not ZDR per its documentation. EU endpoints, your own gateway or local models keep processing under control.

How does Crush differ from Claude Code and OpenCode?

Claude Code comes from the model vendor Anthropic, is proprietary and geared to Claude models. OpenCode from Anomaly is a separate, model-agnostic project under the MIT license with an additional desktop app. Crush is model-agnostic as well, relies heavily on language servers for context, is configured through a Bash script and reports its own state to herdr. Its FSL-1.1-MIT license, however, is not an open-source license in the OSI sense.

Introduce coding agents safely in your company

We support selection, model access in the EU, permission design and cost control.