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

Crush CLI is an open-source command-line AI coding agent from Charm that runs inside your terminal and connects your code, tools, and preferred LLM provider. You can use it to request code changes, debug project behavior, inspect files, and maintain separate work sessions for different projects.

The CLI is ideal for developers who want an AI coding agent in the terminal. It works with OpenAI, Anthropic Claude, Google Gemini, Groq, OpenRouter, Vercel AI Gateway, Amazon Bedrock, Azure OpenAI, Vertex AI, local OpenAI-compatible providers, and other supported model routes.

Features

• Multi-Model Support: Choose from built-in providers or add your own OpenAI-compatible or Anthropic-compatible API route.
• Mid-Session Model Switching: Change models during a session while keeping the working context.
• Session Management: Keep multiple work sessions and project contexts, then return to the session that matches your current codebase.
• LSP Integration: Add language servers such as gopls, typescript-language-server, or nil so Crush can read richer code context.
• MCP Server Support: Connect Model Context Protocol servers through stdio, HTTP, or Server-Sent Events.
• Cross-Platform Terminal Support: Run Crush on macOS, Linux, Windows PowerShell, WSL, Android, FreeBSD, OpenBSD, and NetBSD.
• Project and Global Configuration: Store settings in a local project file or a user-level config file, depending on how you want a workspace to behave.
• Agent Skills Support: Load reusable skills from global and project directories, including .agents/skills, .crush/skills, and related paths.
• Local Logging: Read recent logs with the crush logs command, or turn on debug logging when you need more detail.

See It In Action

Installation

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

Quick Install Commands

Debian / Ubuntu

On Debian-based systems, 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

You can also download prebuilt packages and binaries from the Crush GitHub releases page. Release assets include builds for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD, as well as Debian and RPM packages.

How to Use Crush CLI

After installation, open a terminal inside the project you want Crush to work on and run:

crush

Crush starts an interactive terminal session for that project. On first use, it asks for a model provider or API key. You can also set provider credentials before launch with environment variables.

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. Select a provider or enter the API key that matches your model backend.
5. Ask the Crush agent to inspect files, explain code, write patches, debug errors, or continue a project session.

Set provider API keys

Set environment variables before launch when you move between projects or run Crush inside scripts.

Local model setups can use OpenAI-compatible routes through Ollama, llama.cpp, LM Studio, LiteLLM, or another compatible endpoint. In that case, configure the provider base URL and model list in crush.json.

Work with project sessions

Crush keeps work in sessions. A session can hold the current conversation, project context, tool activity, and coding task history.

If two Crush clients connect to the same working directory through the same backend, they share the same workspace state. Use the session picker to return to a previous task and keep its context.

This matters for longer coding jobs. You can keep one session for a refactor, another for debugging, and another for repository questions, then switch back to the matching context later.

Configuration

Crush reads configuration from the project first, then from the user-level config. The priority order is .crush.json, crush.json, and $HOME/.config/crush/crush.json. Temporary application state is stored separately under $HOME/.local/share/crush/crush.json on Unix-like systems or %LOCALAPPDATA%\crush\crush.json on Windows.

You can override the user config and data locations with CRUSH_GLOBAL_CONFIG and CRUSH_GLOBAL_DATA. A project-level config is the right place for repository-specific LSPs, MCP servers, context paths, provider defaults, permission rules, and ignored files.

Add LSP context

Language Server Protocol support adds structured code context to Crush. Add only the language servers your project already uses or can install reliably.

{
  "$schema": "https://charm.land/crush.json",
  "lsp": {
    "go": {
      "command": "gopls"
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "nix": {
      "command": "nil"
    }
  }
}

Connect MCP servers

MCP servers let Crush call external tools and data sources. Crush supports stdio, HTTP, and Server-Sent Events transports.

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "timeout": 120
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "timeout": 120,
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    }
  }
}

Review project config files before launching Crush in an unfamiliar repository. Shell-style expansion works in commands, arguments, environment values, headers, and URLs. Command substitution inside crush.json can run when Crush loads the file.

Use Agent Skills

Crush can load Agent Skills from global and project folders.

Read More About Skills for AI Coding Agents.

Project skills can live in .agents/skills, .crush/skills, .claude/skills, or .cursor/skills. Global skill folders can live under your user config paths, and you can add more paths through options.skills_paths.

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "skills_paths": [
      "~/.config/crush/skills",
      "./project-skills"
    ]
  }
}

Add context and ignore files

Crush automatically reads global context files such as ~/.config/crush/CRUSH.md and ~/.config/AGENTS.md. Use CRUSH.md for Crush-specific instructions and AGENTS.md for rules that other coding agents can also understand.

Crush respects .gitignore by default. Add a .crushignore file when you want to hide extra files from Crush and keep them in version control.

Control permissions

By default, Crush asks before running tool calls. You can allow specific tools in configuration, or launch with --yolo when you want fewer prompts. Treat --yolo as a high-trust mode for repositories and commands you understand.

{
  "$schema": "https://charm.land/crush.json",
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit"
    ]
  }
}

Check logs and debug output

Crush writes logs to ./.crush/logs/crush.log relative to the project. These commands cover the common log checks:

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

For more detail, run Crush with --debug or set debug options in the config:

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": true,
    "debug_lsp": true
  }
}

Manage provider updates and metrics

Crush can auto-update its provider and model list from Catwalk, Charm’s public provider database. If you work in a restricted or offline environment, disable this behavior with disable_provider_auto_update or CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1.

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "disable_provider_auto_update": true,
    "disable_metrics": true
  }
}

Crush records pseudonymous usage metadata for product metrics. Prompts and responses are not collected for those metrics. You can opt out with CRUSH_DISABLE_METRICS=1, DO_NOT_TRACK=1, or the disable_metrics config option.

Alternatives & Related Resources

• Best Free CLI AI Coding Agents: Compare terminal-based AI coding agents for local development, repository work, and autonomous coding sessions.
• OpenAI Codex Commands Cheat Sheet: Review Codex CLI commands, flags, config keys, MCP usage, and terminal workflows.
• The Ultimate Claude Code Resource List: Explore Claude Code agents, skills, plugins, guides, and related coding-agent resources.
• Best & Open-source MCP Servers: Find MCP servers that extend AI assistants with external tools and structured context.
• SmallCode: Compare another local AI coding agent aimed at smaller local LLM workflows.
• Pi Coding Agent: Compare Crush with another free AI coding agent for terminal-based development work.

Pros

• Free terminal install: Install the CLI without buying a separate Crush license, then connect it to your chosen model provider.
• Provider choice: Use hosted APIs, subscription-backed providers, cloud model platforms, or local OpenAI-compatible endpoints.
• Terminal-native workflow: Keep code work, shell commands, logs, and agent sessions in the same environment.
• LSP and MCP support: Add code intelligence through language servers and connect external tools through MCP.
• Wide platform coverage: Use the same agent across macOS, Linux, Windows, BSD systems, and Android terminal environments.
• Public GitHub repository: Inspect the code, releases, issues, and license before adopting it for a development workflow.

Cons

• Model access is separate: The CLI is free to install. The model provider you connect may charge for API usage or require a paid plan.
• Terminal setup required: You need to be comfortable with package managers, environment variables, and JSON config files.
• Config files can be sensitive: Project config can include provider keys, headers, shell expansion, MCP commands, and permission settings.
• Metrics are enabled by default: Crush records pseudonymous usage metadata. Prompts and responses are not collected for metrics, and you can opt out with CRUSH_DISABLE_METRICS=1 or a config setting.

FAQs

Q: Do I need a paid AI account after installing Crush?
A: The CLI installation is free. The model backend is separate. Hosted providers may require paid API credits or an active subscription. Local endpoints need a running model server.

Q: Should I use Crush with hosted models or local models?
A: Hosted models usually provide stronger coding performance and simpler setup. Local models keep traffic on your own machine or network. Capability depends on the model and hardware.

Q: What should I check before using Crush in a private repository?
A: Check the provider, config files, MCP commands, permission rules, and ignored paths. Your selected model provider receives the prompts and code context you send through Crush. Keep secrets out of project config and review MCP entries from unfamiliar repos.

Q: When should I use a project-level crush.json file?
A: Use project-level config for repository-specific LSPs, MCP servers, provider defaults, permission rules, and context files. Use global config for personal preferences that should follow you across projects.

Q: What can I do when Crush misses code context?
A: Start from the project root, check .gitignore and .crushignore, confirm the relevant files are reachable, and add LSP config for the project language. Run crush logs when context or tool calls look wrong.

Q: How should I choose between Crush CLI, Gemini CLI, Claude Code, and Codex CLI?
A: Choose Crush when provider choice, terminal sessions, LSP context, and MCP config matter most. Choose a provider-specific CLI when you want the tightest path to that provider’s own models and account system.

Last Updated: July 04, 2026