Crush Terminal Coding Assistant
A multi-model terminal coding assistant that connects your codebase, tools, and workflows to the LLM you choose.
- Source repo
- charmbracelet/crush
- Stars
- ★ 29k
- Last updated
- today
- License
- NOASSERTION
- Primary language
- Go
- FA score
- 43/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer who uses OpenAI, Anthropic, Gemini, or another configured provider and wants to change models mid-task without losing the conversation context.
- Not a fit if
- Users who won't review project config before launching Crush (crushrc and crush.json run shell commands)
- Teams wanting one official pricing and account model; you pay each provider yourself
- Source review
- 43/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
Crush is Charm’s terminal-based coding assistant for working with a project’s code, language models, and configured developer tools. It supports multiple project work sessions and lets users switch LLMs during a session while retaining context. LSP integrations provide additional code context, while MCP servers can be connected over stdio, HTTP, or SSE. Crush is installed and run as a local CLI across macOS, Linux, Windows, Android, and several BSD systems; model access comes from Hyper, provider credentials, or custom compatible endpoints. Tool calls request permission by default, with configuration to allow selected tools, disable tools, or bypass prompts using --yolo.
Run crush, then use ctrl+l to open the model picker and authenticate a provider. Crush loads .crush.json, crush.json, or a global crush.json for providers, LSPs, MCP servers, permissions, and skills, and it loads project and global context files. It can use configured LSPs to add code context and connect to MCP servers with stdio, http, or sse transports. Clients using the same resolved --cwd share a workspace’s session list, message history, permission queue, LSP state, and MCP state. Logs are written to ./.crush/logs/crush.log and can be inspected with crush logs.
- A developer who uses OpenAI, Anthropic, Gemini, or another configured provider and wants to change models mid-task without losing the conversation context.
- An engineer working across several repositories who needs multiple saved coding sessions per project and wants another terminal client to view a shared workspace.
- A Go, TypeScript, or Nix developer who wants configured
gopls,typescript-language-server, ornilto provide extra context to the coding assistant. - A team with internal MCP services that wants to expose filesystem, GitHub, or other capabilities to a terminal coding workflow over stdio, HTTP, or SSE.
- A local-model user running Ollama, llama.cpp, LM Studio, LiteLLM, or omlx who wants model discovery or explicit local model configuration.
How do you install or deploy this agent?
Install with a documented package method, for example brew install charmbracelet/tap/crush or npm install -g @charmland/crush; Go users can run go install github.com/charmbracelet/crush@latest. Start it in a project with crush, press ctrl+l, and complete authentication for the selected provider. For environment-based credentials, set OPENAI_API_KEY for OpenAI or ANTHROPIC_API_KEY for Anthropic before starting Crush.
How do you use this agent?
From the project directory, run crush. For project configuration, create .crush.json; for example, configure Go LSP with {"$schema":"https://charm.land/crush.json","lsp":{"go":{"command":"gopls"}}}. To add an HTTP MCP server, define an entry under mcp with a name, "type":"http", and a url; static credentials can be supplied through headers. Tool calls ask for permission by default; use permissions.allowed_tools to permit specific tools, or use crush --yolo cautiously to skip all prompts.
What are this agent's strengths and limitations?
- Model switching within a session preserves context instead of tying a coding workflow to one provider.
- It combines LSP context with MCP connectivity across stdio, HTTP, and SSE transports.
- It documents custom OpenAI-compatible and Anthropic-compatible providers as well as several local model services.
- Multiple clients on the same
--cwdcan share sessions, histories, permission queues, LSP state, and MCP state.
- You must choose and authenticate a model provider; the repository does not provide a single pricing or account model for third-party providers.
- A
$(...)expression incrush.jsonruns at load time with shell privileges, so unreviewed project configuration is a documented security risk. - Permissions, MCP servers, LSPs, and provider settings introduce setup and governance work;
--yolobypasses every tool permission prompt. - Repository metadata says
NOASSERTIONwhile the README links to FSL-1.1-MIT, so adopters should verify the applicable license.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Crush Terminal Coding Assistant This agent | 43 · Major gaps | CLIFree + model costs | ★ 29k | today | Go | OpenAI API · Claude API |
| Stripe AI | 50 · Major gaps | Library / SDKFree + model costs | ★ 2k | 1d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| MiniCode | 50 · Major gaps | CLIFree + model costs | ★ 1.2k | 28d ago | TypeScript | Claude API |
| Kode CLI | 44 · Major gaps | CLIFree + model costs | ★ 5.2k | 3d ago | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows default permission prompts (permissions allow requires explicit config), but --yolo skips all prompts, and crushrc is trusted code that can execute arbitrary commands, lacking least-privilege isolation. Data flow transparency is limited; no detailed explanation of what data is sent to LLMs or third parties. Sensitive data handling: API keys stored via env vars or config, but no encryption at rest mentioned. Dependency security: many dependencies in go.mod, but no vulnerability scanning or security audit evidence. External effects: tool can execute shell commands, modify files, create commits, but defaults to confirmation. Rollback mechanism not mentioned. Source attribution: attribution settings exist, but not verified.
Self-consistency: README features and config examples are mostly consistent, but some details (e.g., JSON config deprecation) not fully elaborated. Dependency availability: many dependencies with pinned versions, but no availability guarantees. Failure messages: no examples of error handling or user prompts.
Audience and scenarios clear, targeting developers, supporting multiple platforms and LLMs. Capability boundaries clear, supporting LSP, MCP, skills, but no explicit limits. Trigger precision: skills can be configured user-invocable and disable-model-invocation, but default behavior not detailed. Environment fit: supports multiple platforms, but no detailed environment-specific configuration.
Information architecture clear, README well-structured with sections on config, install, usage. Install notes detailed, covering multiple package managers. Naming stability: project and command names stable, but no API stability guarantee. Examples and FAQ rich, but FAQ section missing. Known limitations not explicitly listed. License is FSL-1.1-MIT, but metadata is NOASSERTION, and license text includes MIT future license, but versioning not explicit. Versioning/changelog not provided. Maintenance responsibility: CLA and CI present, but maintainers not explicit.
Output usability: TUI and multiple output formats, but not detailed. Marginal value: multi-model, LSP, MCP features, but no comparison with existing tools. Cost-benefit: free and open source, but no performance or resource consumption data.
Claim traceability: feature claims in README lack specific implementation evidence. Cross-source corroboration: no third-party verification. Fact-inference separation: no clear distinction between facts and inferences.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- --yolo mode skips all permission prompts, high risk, use with caution.
- crushrc and crush.json are treated as trusted code and can execute arbitrary commands; ensure sources are trusted.
- License metadata is NOASSERTION, actual is FSL-1.1-MIT, verify compliance.
- No rollback mechanism provided; operations may be irreversible.
- Many dependencies, no security audit evidence.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Subagents, Sysadmin Mode, and PGP/SSH Prompts This is a big one! Crush can now run a team of subagents, permissions are much more flexible, and you can now do GPG and SSH auth right inside Crush! Read on for more. 👩🏼🐰👩🏽 Subagents At last, subagents. Crush can now spawn a little team of friendly subagents in the background, as well as check on them, send them mid-run follow-ups, stop them, or move them to a different model. <p><img width="600" alt="image" src="https://github.com/user-attachments/assets/a8f4f437-dd9a-46bb-ab31-65a14b84c07a" /></p> …View on GitHub ↗ -
Release notes excerpt
Hooks, Catwalk v3! A big one! Crush now runs on Catwalk v3, hooks can see every part of a run, and editors that host Crush get a whole new set of tools to feel right at home. Hooks, everywhere 🪝 Hooks are no longer just about tools. They can now follow the whole run: sessions, turns, permissions and more! Hooks can now step in after a tool runs, too. Redact secrets from the output before the model sees them, add a note, or stop the turn. If the tool already did something it shouldn't have, your hook can tell the model "you committed without running the tests." ```bash …View on GitHub ↗ -
Release notes excerpt
Keanu, OAuth re-sign-in and a crash fix This patch was brought to you by our team and our favorite contributors! The Keanu Theme > [!CAUTION] > This will make you feel like a hacker <img width="800" src="https://github.com/user-attachments/assets/061f5473-9f78-49a4-8aa5-dc54ae955189" /> A theme made by @andreynering 🎉 💻 Fixed! • Fixed a crash when parallel tool calls finish together, by @andreynering • Fixed OAuth sign-in and credential refresh, by @taciturnaxolotl • Ctrl+C now interrupts startup, and custom provider model discovery no longer stalls it, by @taciturnaxolotl …View on GitHub ↗
FAQ
Can I use my own or local models?
Will it run tools without asking?
permissions.allowed_tools for selected tools. --yolo skips all permission prompts and is explicitly documented as something to use with care.Which MCP connections are supported?
stdio, endpoints through http, and Server-Sent Events through sse. HTTP and SSE servers can also use OAuth.Are prompts and responses collected as metrics?
CRUSH_DISABLE_METRICS=1 or configure disable_metrics to opt out.