Crush CLI: Free AI Coding Agent for Terminal Code Editing and Debugging

Crush is a source-available command-line AI coding agent from Charm that runs inside your terminal and connects your code, tools, and chosen LLM provider. You can ask it to inspect files, change code, debug errors, run project tools, and keep separate sessions for different tasks.

Charm Hyper is the official provider and has a free tier. Crush also connects to Anthropic, OpenAI, Google Gemini, OpenRouter, Amazon Bedrock, Azure OpenAI, Vertex AI, local model servers, and many other provider routes. You can switch models during a session without losing the conversation context.

Features

• Multi-Provider Model Access: Connect built-in providers, Charm Hyper, local model servers, or custom OpenAI-compatible and Anthropic-compatible APIs.
• Mid-Session Model Switching: Change models while preserving the active session context.
• Session Management: Maintain several coding sessions per project and reopen a previous conversation from the session manager.
• Structured Questions: The agent can pause for single-choice, multiple-choice, yes-or-no, or free-form answers before it continues a task.
• LSP Refactoring Tools: Language servers provide code context, symbol renaming, and whole-symbol replacement for supported project languages.
• MCP Server Connections: Connect MCP servers over stdio, HTTP, or Server-Sent Events, with OAuth available for compatible HTTP and SSE servers.
• Cross-Platform Terminal Support: Run Crush on macOS, Linux, Windows PowerShell, WSL, Android, FreeBSD, OpenBSD, NetBSD, and illumos.
• Shell-Based Configuration: Use a project or global crushrc file with Bash syntax that works across supported operating systems.
• Agent Skills: Load reusable skills from global folders, project folders, or extra paths defined in your configuration.
• Permission Controls: Approve selected tools, hide tools from the agent, or run a trusted workspace with --yolo.

See It In Action

Installation

You can install Crush with a package manager, a GitHub release binary, or Go.

Quick Install Commands

Nix users can also install the current NUR package at nur.repos.charmbracelet.crush. The official NUR module configures Crush for NixOS or Home Manager.

Debian / Ubuntu

On a Debian-based system, add the Charm package repository and install Crush through apt:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install crush

Fedora / RHEL

On Fedora, RHEL, or CentOS, add the Charm yum repository:

echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install crush

Manual Download

Prebuilt packages and binaries are available from the Crush GitHub releases page. Release assets include Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD builds, plus Debian and RPM packages. The Go installation command also works on illumos. Oracle Solaris requires the sqlite3_dotlk build tag.

How to Use Crush CLI

Open a terminal in your project directory and start the interactive interface:

crush

The quickest first setup is to select a Charm Hyper model and follow the authentication steps. Hyper is subscription based, has a free tier, and uses zero data retention.

Press Ctrl+L to open the model picker when you want another provider, then choose the provider and paste its API key.

1. Install Crush with your preferred package manager.
2. Open your repository or project folder in the terminal.
3. Run crush to start the TUI.
4. Authenticate with Hyper or open the model picker to select another provider.
5. Ask the agent to inspect files, explain code, write a patch, run project tools, or debug an error.

Set provider API keys

Environment variables supply credentials before launch and work well for scripts or provider-specific project setups.

Crush can discover models from Ollama, llama.cpp, OMLX, LM Studio, and LiteLLM. Add the local provider in crushrc and leave its model list empty when you want automatic discovery.

Work with project sessions

Each session stores its conversation, project context, tool activity, and coding task history. Open the session manager when you want to continue an earlier task.

Two clients that use the same backend and resolved working directory join the same workspace, but each new client starts a fresh session by default. Select the active session to mirror another client’s conversation. The first client also sets workspace-wide --yolo and --debug values until the workspace closes.

Configuration

Crush now uses crushrc, a Bash-based configuration format with Crush-specific commands. The same syntax works on Unix-like systems and Windows because Crush includes its own Bash interpreter. Existing JSON configuration remains compatible, but the project marks that format as deprecated.

Crush loads ./.crushrc first, then ./crushrc, followed by ~/.config/crush/crushrc on Unix-like systems or %USERPROFILE%\.config\crush\crushrc on Windows. Store repository rules in a project file and personal defaults in the global file. Application state remains under the platform data directory and is not executable configuration.

Treat every crushrc and legacy crush.json as trusted code. A crushrc runs in a full shell, and command substitution in JSON runs when Crush loads the file. Review project configuration before launching Crush in an unfamiliar repository.

Add LSP context

Language Server Protocol connections provide structured code context and power the lsp_rename and lsp_replace_symbol tools. Register only language servers that are installed for your project.

# crushrc
lsp add go --command "gopls"
lsp add typescript --command "typescript-language-server" --args --stdio
lsp add nix --command "nil"

Connect MCP servers

Crush connects to MCP servers through stdio, HTTP, and SSE. HTTP and SSE servers can use OAuth, including pre-registered client credentials for services that do not offer dynamic client registration.

# crushrc
mcp add filesystem --command node --args /path/to/mcp-server.js \
  --timeout 120 --env NODE_ENV production
mcp add github \
  --type http \
  --url "https://api.githubcopilot.com/mcp/" \
  --timeout 120 \
  --header Authorization "Bearer $GH_PAT"

Set oauth to true for an HTTP or SSE server that uses the built-in authorization-code flow:

{
  "mcp": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp",
      "oauth": true
    }
  }
}

A server without dynamic client registration also needs a pre-registered client ID, client secret, and callback port.

Use Agent Skills

Crush follows the Agent Skills open standard and discovers folders that contain a SKILL.md file.

Read More About Skills for AI Coding Agents.

Project skills can live in .agents/skills, .crush/skills, .claude/skills, or .cursor/skills. Global skill locations include the Crush and Agent Skills config folders. Add more directories in crushrc:

option skill-path "$HOME/squid-skills" "./project-skills"

A skill with user-invocable: true appears in the command palette. Add disable-model-invocation: true when you want manual invocation without automatic model access.

Add context and ignore files

Crush reads ~/.config/crush/CRUSH.md for product-specific instructions and ~/.config/AGENTS.md for rules shared with other coding agents. Add another file or a directory of Markdown context through option global-context-path.

Crush respects .gitignore by default. Add .crushignore when a tracked file or directory should remain outside the agent’s context.

Control permissions

Crush asks before running tool calls by default. Allow trusted tools or deny tools that should stay hidden from the agent:

permissions allow view ls grep edit
permissions deny bash sourcegraph

The --yolo flag skips every permission prompt. Reserve it for repositories and commands you have already reviewed.

Check logs and debug output

Crush writes project logs to ./.crush/logs/crush.log. Use these commands to read or follow recent output:

# Print the last 1000 lines
crush logs
# Print the last 500 lines
crush logs --tail 500
# Follow logs in real time
crush logs --follow

Run crush --debug for more detail, or enable debug output in crushrc:

option debug true
option debug-lsp true

Manage provider updates and metrics

Crush checks Catwalk, Charm’s public provider database, for updated provider and model metadata. Disable the check in crushrc with option provider-auto-update false or set CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1 in a restricted environment. The crush update-providers command can load Catwalk data from the network, a custom URL, a local file, or the embedded copy.

Crush records pseudonymous usage metadata tied to a device-specific hash. Prompts and responses are excluded. Set CRUSH_DISABLE_METRICS=1 or DO_NOT_TRACK=1 to opt out.

Alternatives & Related Resources

• Best Free CLI AI Coding Agents
• OpenAI Codex Commands Cheat Sheet
• The Ultimate Claude Code Resource List
• Best & Open-source MCP Servers
• SmallCode
• Pi Coding Agent

Pros

• Free CLI installation
• Wide model-provider choice
• Terminal-native coding sessions
• LSP and MCP integrations
• Runs across desktop and BSD systems

Cons

• Model access may cost extra
• Project configuration executes trusted code
• Metrics require manual opt-out

FAQs

Q: Do I need a paid AI account after installing Crush?
A: The CLI is free to install. Charm Hyper has a free tier and paid subscriptions. Other hosted providers may require API credits or an active plan, while local models need compatible hardware and a running model server.

Q: Is Crush open source?
A: Crush publishes its source under FSL-1.1-MIT. The license permits use, modification, and redistribution for purposes that do not compete with Crush or another Charm offering built with the software. Each released version receives an MIT license on the second anniversary of its publication.

Q: Should I use Crush with hosted or local models?
A: Hosted models remove the need to run inference on your own hardware. A local endpoint keeps model traffic on your own machine or network. The model, context window, and available hardware determine actual capability.

Q: What should I check before using Crush in a private repository?
A: Review the selected provider, project configuration, MCP commands, permission rules, and ignored paths. Your chosen provider receives the prompts and code context sent through Crush. Keep secrets outside tracked configuration and inspect unfamiliar crushrc files before launch.

Q: What can I do when Crush misses code context?
A: Start from the project root, inspect .gitignore and .crushignore, confirm that the relevant files are reachable, and register the project’s language server. Run crush logs when context retrieval or tool calls fail.

Q: Why does clipboard copy and paste fail on Linux or BSD?
A: Wayland environments need wl-copy and wl-paste. X11 environments need xclip or xsel. Windows and macOS use native clipboard support.

Q: How should I choose between Crush, Gemini CLI, Claude Code, and Codex CLI?
A: Crush fits projects that need several model providers, persistent terminal sessions, LSP context, Agent Skills, and configurable MCP servers. A provider-specific CLI has a more direct connection to that provider’s models, authentication, and account plan.

Last Updated: August 01, 2026