1# Crush
2
3<p align="center">
4 <a href="https://stuff.charm.sh/crush/charm-crush.png"><img width="450" alt="Charm Crush Logo" src="https://github.com/user-attachments/assets/cf8ca3ce-8b02-43f0-9d0f-5a331488da4b" /></a><br />
5 <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>
6 <a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/actions/workflows/build.yml/badge.svg" alt="Build Status"></a>
7</p>
8
9<p align="center">Your new coding bestie, now available in your favourite terminal.<br />Your tools, your code, and your workflows, wired into your LLM of choice.</p>
10<p align="center">终端里的编程新搭档，<br />无缝接入你的工具、代码与工作流，全面兼容主流 LLM 模型。</p>
11
12<p align="center"><img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/58280caf-851b-470a-b6f7-d5c4ea8a1968" /></p>
13
14## Features
15
16- **Multi-Model:** choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
17- **Flexible:** switch LLMs mid-session while preserving context
18- **Session-Based:** maintain multiple work sessions and contexts per project
19- **LSP-Enhanced:** Crush uses LSPs for additional context, just like you do
20- **Extensible:** add capabilities via MCPs (`http`, `stdio`, and `sse`)
21- **Works Everywhere:** first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD, and NetBSD
22- **Industrial Grade:** built on the Charm ecosystem, powering 25k+ applications, from leading open source projects to business-critical infrastructure
23
24## Installation
25
26Use a package manager:
27
28```bash
29# Homebrew
30brew install charmbracelet/tap/crush
31
32# NPM
33npm install -g @charmland/crush
34
35# Arch Linux (btw)
36yay -S crush-bin
37
38# Nix
39nix run github:numtide/nix-ai-tools#crush
40
41# FreeBSD
42pkg install crush
43```
44
45Windows users:
46
47```bash
48# Winget
49winget install charmbracelet.crush
50
51# Scoop
52scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git
53scoop install crush
54```
55
56<details>
57<summary><strong>Nix (NUR)</strong></summary>
58
59Crush is available via the official Charm [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`, which is the most up-to-date way to get Crush in Nix.
60
61You can also try out Crush via the NUR with `nix-shell`:
62
63```bash
64# Add the NUR channel.
65nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
66nix-channel --update
67
68# Get Crush in a Nix shell.
69nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
70```
71
72### NixOS & Home Manager Module Usage via NUR
73
74Crush provides NixOS and Home Manager modules via NUR.
75You can use these modules directly in your flake by importing them from NUR. Since it auto detects whether its a home manager or nixos context you can use the import the exact same way :)
76
77```nix
78{
79 inputs = {
80 nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
81 nur.url = "github:nix-community/NUR";
82 };
83
84 outputs = { self, nixpkgs, nur, ... }: {
85 nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
86 system = "x86_64-linux";
87 modules = [
88 nur.modules.nixos.default
89 nur.repos.charmbracelet.modules.crush
90 {
91 programs.crush = {
92 enable = true;
93 settings = {
94 providers = {
95 openai = {
96 id = "openai";
97 name = "OpenAI";
98 base_url = "https://api.openai.com/v1";
99 type = "openai";
100 api_key = "sk-fake123456789abcdef...";
101 models = [
102 {
103 id = "gpt-4";
104 name = "GPT-4";
105 }
106 ];
107 };
108 };
109 lsp = {
110 go = { command = "gopls"; enabled = true; };
111 nix = { command = "nil"; enabled = true; };
112 };
113 options = {
114 context_paths = [ "/etc/nixos/configuration.nix" ];
115 tui = { compact_mode = true; };
116 debug = false;
117 };
118 };
119 };
120 }
121 ];
122 };
123 };
124}
125```
126
127</details>
128
129<details>
130<summary><strong>Debian/Ubuntu</strong></summary>
131
132```bash
133sudo mkdir -p /etc/apt/keyrings
134curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
135echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
136sudo apt update && sudo apt install crush
137```
138
139</details>
140
141<details>
142<summary><strong>Fedora/RHEL</strong></summary>
143
144```bash
145echo '[charm]
146name=Charm
147baseurl=https://repo.charm.sh/yum/
148enabled=1
149gpgcheck=1
150gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
151sudo yum install crush
152```
153
154</details>
155
156Or, download it:
157
158- [Packages][releases] are available in Debian and RPM formats
159- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
160
161[releases]: https://github.com/charmbracelet/crush/releases
162
163Or just install it with Go:
164
165```
166go install github.com/charmbracelet/crush@latest
167```
168
169> [!WARNING]
170> Productivity may increase when using Crush and you may find yourself nerd
171> sniped when first using the application. If the symptoms persist, join the
172> [Slack][slack] or [Discord][discord] and nerd snipe the rest of us.
173
174## Getting Started
175
176The quickest way to get started is to grab an API key for your preferred
177provider such as Anthropic, OpenAI, Groq, OpenRouter, or Vercel AI Gateway and just start
178Crush. You'll be prompted to enter your API key.
179
180That said, you can also set environment variables for preferred providers.
181
182| Environment Variable | Provider |
183| --------------------------- | -------------------------------------------------- |
184| `HYPER_API_KEY` | Charm Hyper |
185| `ANTHROPIC_API_KEY` | Anthropic |
186| `OPENAI_API_KEY` | OpenAI |
187| `VERCEL_API_KEY` | Vercel AI Gateway |
188| `GEMINI_API_KEY` | Google Gemini |
189| `SYNTHETIC_API_KEY` | Synthetic |
190| `ZAI_API_KEY` | Z.ai |
191| `MINIMAX_API_KEY` | MiniMax |
192| `HF_TOKEN` | Hugging Face Inference |
193| `CEREBRAS_API_KEY` | Cerebras |
194| `OPENROUTER_API_KEY` | OpenRouter |
195| `IONET_API_KEY` | io.net |
196| `ALIBABA_SINGAPORE_API_KEY` | Alibaba (Singapore) |
197| `GROQ_API_KEY` | Groq |
198| `AVIAN_API_KEY` | Avian |
199| `OPENCODE_API_KEY` | OpenCode Zen & Go |
200| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
201| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
202| `AWS_ACCESS_KEY_ID` | Amazon Bedrock (Claude) |
203| `AWS_SECRET_ACCESS_KEY` | Amazon Bedrock (Claude) |
204| `AWS_REGION` | Amazon Bedrock (Claude) |
205| `AWS_PROFILE` | Amazon Bedrock (Custom Profile) |
206| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock |
207| `AZURE_OPENAI_API_ENDPOINT` | Azure OpenAI models |
208| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
209| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
210
211### Subscriptions
212
213If you prefer subscription-based usage, here are some plans that work well in
214Crush:
215
216- [Synthetic](https://synthetic.new/pricing)
217- [GLM Coding Plan](https://z.ai/subscribe)
218- [Kimi Code](https://www.kimi.com/membership/pricing)
219- [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan)
220
221### By the Way
222
223Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
224
225Crush’s default model listing is managed in [Catwalk](https://github.com/charmbracelet/catwalk), a community-supported, open source repository of Crush-compatible models, and you’re welcome to contribute.
226
227<a href="https://github.com/charmbracelet/catwalk"><img width="174" height="174" alt="Catwalk Badge" src="https://github.com/user-attachments/assets/95b49515-fe82-4409-b10d-5beb0873787d" /></a>
228
229## Configuration
230
231> [!TIP]
232> Crush ships with a builtin `crush-config` skill for configuring itself. In
233> many cases you can simply ask Crush to configure itself.
234
235Crush runs great with no configuration. That said, if you do need or want to
236customize Crush, configuration can be added either local to the project itself,
237or globally, with the following priority:
238
2391. `.crush.json`
2402. `crush.json`
2413. `$HOME/.config/crush/crush.json`
242
243Configuration itself is stored as a JSON object:
244
245```json
246{
247 "this-setting": { "this": "that" },
248 "that-setting": ["ceci", "cela"]
249}
250```
251
252As an additional note, Crush also stores ephemeral data, such as application
253state, in one additional location:
254
255```bash
256# Unix
257$HOME/.local/share/crush/crush.json
258
259# Windows
260%LOCALAPPDATA%\crush\crush.json
261```
262
263> [!TIP]
264> You can override the user and data config locations by setting:
265>
266> - `CRUSH_GLOBAL_CONFIG`
267> - `CRUSH_GLOBAL_DATA`
268
269### LSPs
270
271Crush can use LSPs for additional context to help inform its decisions, just
272like you would. LSPs can be added manually like so:
273
274```json
275{
276 "$schema": "https://charm.land/crush.json",
277 "lsp": {
278 "go": {
279 "command": "gopls",
280 "env": {
281 "GOTOOLCHAIN": "go1.24.5"
282 }
283 },
284 "typescript": {
285 "command": "typescript-language-server",
286 "args": ["--stdio"]
287 },
288 "nix": {
289 "command": "nil"
290 }
291 }
292}
293```
294
295### MCPs
296
297Crush also supports Model Context Protocol (MCP) servers through three transport
298types: `stdio` for command-line servers, `http` for HTTP endpoints, and `sse`
299for Server-Sent Events.
300
301Shell-style value expansion (`$VAR`, `${VAR:-default}`, `$(command)`, quoting,
302nesting) works in `command`, `args`, `env`, `headers`, and `url`, so
303file-based secrets work out of the box. You can use values like `"$TOKEN"`
304or `"$(cat /path/to/secret/token)"`. Expansion runs through Crush's embedded
305shell, so the same syntax works on every supported system, Windows included.
306
307Unset variables expand to the empty string by default, matching bash. For
308required credentials, use `${VAR:?message}` so an unset variable fails loudly
309at load time with `message` instead of silently resolving to empty:
310
311```json
312{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }
313```
314
315Headers (both MCP `headers` and provider `extra_headers`) whose value
316resolves to the empty string are dropped from the outgoing request rather
317than sent as `Header:`. That keeps optional env-gated headers like
318`"OpenAI-Organization": "$OPENAI_ORG_ID"` clean when the variable is unset.
319
320Provider `extra_body` is a non-expanding JSON passthrough; put env-driven
321values in `extra_headers` or the provider's `api_key` / `base_url`, all of
322which do expand.
323
324> **Security note:** `crush.json` is trusted code. Any `$(...)` in it runs at
325> load time with your shell's privileges, before the UI appears. Don't launch
326> Crush in a directory whose `crush.json` you haven't reviewed.
327
328```json
329{
330 "$schema": "https://charm.land/crush.json",
331 "mcp": {
332 "filesystem": {
333 "type": "stdio",
334 "command": "node",
335 "args": ["/path/to/mcp-server.js"],
336 "timeout": 120,
337 "disabled": false,
338 "disabled_tools": ["some-tool-name"],
339 "env": {
340 "NODE_ENV": "production"
341 }
342 },
343 "github": {
344 "type": "http",
345 "url": "https://api.githubcopilot.com/mcp/",
346 "timeout": 120,
347 "disabled": false,
348 "disabled_tools": ["create_issue", "create_pull_request"],
349 "headers": {
350 "Authorization": "Bearer $GH_PAT"
351 }
352 },
353 "streaming-service": {
354 "type": "sse",
355 "url": "https://example.com/mcp/sse",
356 "timeout": 120,
357 "disabled": false,
358 "headers": {
359 "API-Key": "$(echo $API_KEY)"
360 }
361 }
362 }
363}
364```
365
366### Hooks
367
368Crush has preliminary support for hooks. For details, see
369[the hook guide](./docs/hooks/).
370
371### Global context files
372
373Crush automatically includes two files for cross-project instructions.
374
375- `~/.config/crush/CRUSH.md`: Crush-specific rules that would confuse other
376 agentic coding tools. If you only use Crush, this is the only one you need to
377 edit.
378- `~/.config/AGENTS.md`: generic instructions that other coding tools might
379 read. Avoid referring to Crush-specific features or workflows here. You
380 probably only care about this if you use multiple agentic coding tools and
381 want to share instructions between them.
382
383You can customize these paths using the `global_context_paths` option in your
384configuration:
385
386```jsonc
387{
388 "$schema": "https://charm.land/crush.json",
389 "options": {
390 "global_context_paths": [
391 "~/path/to/custom/context/file.md",
392 "/full/path/to/folder/of/files/" // recursively load all .md files in folder
393 ]
394 }
395}
396```
397
398### Ignoring Files
399
400Crush respects `.gitignore` files by default, but you can also create a
401`.crushignore` file to specify additional files and directories that Crush
402should ignore. This is useful for excluding files that you want in version
403control but don't want Crush to consider when providing context.
404
405The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
406in the root of your project or in subdirectories.
407
408### Allowing Tools
409
410By default, Crush will ask you for permission before running tool calls. If
411you'd like, you can allow tools to be executed without prompting you for
412permissions. Use this with care.
413
414```json
415{
416 "$schema": "https://charm.land/crush.json",
417 "permissions": {
418 "allowed_tools": [
419 "view",
420 "ls",
421 "grep",
422 "edit",
423 "mcp_context7_get-library-doc"
424 ]
425 }
426}
427```
428
429You can also skip all permission prompts entirely by running Crush with the
430`--yolo` flag. Be very, very careful with this feature.
431
432### Disabling Built-In Tools
433
434If you'd like to prevent Crush from using certain built-in tools entirely, you
435can disable them via the `options.disabled_tools` list. Disabled tools are
436completely hidden from the agent.
437
438```json
439{
440 "$schema": "https://charm.land/crush.json",
441 "options": {
442 "disabled_tools": ["bash", "sourcegraph"]
443 }
444}
445```
446
447To disable tools from MCP servers, see the [MCP config section](#mcps).
448
449### Disabling Skills
450
451If you'd like to prevent Crush from using certain skills entirely, you can
452disable them via the `options.disabled_skills` list. Disabled skills are hidden
453from the agent, including builtin skills and skills discovered from disk.
454
455```json
456{
457 "$schema": "https://charm.land/crush.json",
458 "options": {
459 "disabled_skills": ["crush-config"]
460 }
461}
462```
463
464### Agent Skills
465
466Crush supports the [Agent Skills](https://agentskills.io) open standard for
467extending agent capabilities with reusable skill packages. Skills are folders
468containing a `SKILL.md` file with instructions that Crush can discover and
469activate on demand.
470
471The global paths we looks for skills are:
472
473* `$CRUSH_SKILLS_DIR`
474* `$XDG_CONFIG_HOME/agents/skills` or `~/.config/agents/skills/`
475* `$XDG_CONFIG_HOME/crush/skills` or `~/.config/crush/skills/`
476* `~/.agents/skills/`
477* `~/.claude/skills/`
478* On Windows, we _also_ look at
479 * `%LOCALAPPDATA%\agents\skills\` or `%USERPROFILE%\AppData\Local\agents\skills\`
480 * `%LOCALAPPDATA%\crush\skills\` or `%USERPROFILE%\AppData\Local\crush\skills\`
481* Additional paths configured via `options.skills_paths`
482
483On top of that, we _also_ load skills in your project from the following
484relative paths:
485
486* `.agents/skills`
487* `.crush/skills`
488* `.claude/skills`
489* `.cursor/skills`
490
491```jsonc
492{
493 "$schema": "https://charm.land/crush.json",
494 "options": {
495 "skills_paths": [
496 "~/.config/crush/skills", // Windows: "%LOCALAPPDATA%\\crush\\skills",
497 "./project-skills",
498 ],
499 },
500}
501```
502
503You can get started with example skills from [anthropics/skills](https://github.com/anthropics/skills):
504
505```bash
506# Unix
507mkdir -p ~/.config/crush/skills
508cd ~/.config/crush/skills
509git clone https://github.com/anthropics/skills.git _temp
510mv _temp/skills/* . && rm -rf _temp
511```
512
513```powershell
514# Windows (PowerShell)
515mkdir -Force "$env:LOCALAPPDATA\crush\skills"
516cd "$env:LOCALAPPDATA\crush\skills"
517git clone https://github.com/anthropics/skills.git _temp
518mv _temp/skills/* . ; rm -r -force _temp
519```
520
521#### User-Invocable Skills
522
523Skills can be made invocable as commands from the commands palette (Ctrl+P). Add `user-invocable: true` to the skill's YAML frontmatter:
524
525```yaml
526---
527name: my-skill
528description: A skill that can be invoked as a command.
529user-invocable: true
530---
531```
532
533User-invocable skills appear in the commands palette with a `user:` or `project:` prefix:
534- Skills from global directories show as `user:skill-name`
535- Skills from project directories show as `project:skill-name`
536
537When invoked, the skill's instructions are loaded into the conversation context.
538
539To prevent the model from auto-triggering a skill (while still allowing user invocation), add `disable-model-invocation: true`:
540
541```yaml
542---
543name: my-skill
544description: Only invocable by users, not the model.
545user-invocable: true
546disable-model-invocation: true
547---
548```
549
550Skills with `disable-model-invocation` won't appear in the model's available skills list but can still be invoked manually by users.
551
552### Desktop notifications
553
554Crush sends desktop notifications when a tool call requires permission and when
555the agent finishes its turn. They're only sent when the terminal window isn't
556focused _and_ your terminal supports reporting the focus state.
557
558```jsonc
559{
560 "$schema": "https://charm.land/crush.json",
561 "options": {
562 "disable_notifications": false, // default
563 },
564}
565```
566
567To disable desktop notifications, set `disable_notifications` to `true` in your
568configuration. On macOS, notifications currently lack icons due to platform
569limitations.
570
571### Initialization
572
573When you initialize a project, Crush analyzes your codebase and creates
574a context file that helps it work more effectively in future sessions.
575By default, this file is named `AGENTS.md`, but you can customize the
576name and location with the `initialize_as` option:
577
578```json
579{
580 "$schema": "https://charm.land/crush.json",
581 "options": {
582 "initialize_as": "AGENTS.md"
583 }
584}
585```
586
587This is useful if you prefer a different naming convention or want to
588place the file in a specific directory (e.g., `CRUSH.md` or
589`docs/LLMs.md`). Crush will fill the file with project-specific context
590like build commands, code patterns, and conventions it discovered during
591initialization.
592
593### Attribution Settings
594
595By default, Crush adds attribution information to Git commits and pull requests
596it creates. You can customize this behavior with the `attribution` option:
597
598```json
599{
600 "$schema": "https://charm.land/crush.json",
601 "options": {
602 "attribution": {
603 "trailer_style": "co-authored-by",
604 "generated_with": true
605 }
606 }
607}
608```
609
610- `trailer_style`: Controls the attribution trailer added to commit messages
611 (default: `assisted-by`)
612 - `assisted-by`: Adds `Assisted-by: Crush:[ModelID]` as specified in [the convention](https://docs.kernel.org/process/coding-assistants.html#attribution)
613 - `co-authored-by`: Adds `Co-Authored-By: Crush <crush@charm.land>`
614 - `none`: No attribution trailer
615- `generated_with`: When true (default), adds `💘 Generated with Crush` line to
616 commit messages and PR descriptions
617
618### Custom Providers
619
620Crush supports custom provider configurations for both OpenAI-compatible and
621Anthropic-compatible APIs.
622
623> [!NOTE]
624> Note that we support two "types" for OpenAI. Make sure to choose the right one
625> to ensure the best experience!
626>
627> - `openai` should be used when proxying or routing requests through OpenAI.
628> - `openai-compat` should be used when using non-OpenAI providers that have OpenAI-compatible APIs.
629
630#### OpenAI-Compatible APIs
631
632Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
633API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
634
635```json
636{
637 "$schema": "https://charm.land/crush.json",
638 "providers": {
639 "deepseek": {
640 "type": "openai-compat",
641 "base_url": "https://api.deepseek.com/v1",
642 "api_key": "$DEEPSEEK_API_KEY",
643 "models": [
644 {
645 "id": "deepseek-chat",
646 "name": "Deepseek V3",
647 "cost_per_1m_in": 0.27,
648 "cost_per_1m_out": 1.1,
649 "cost_per_1m_in_cached": 0.07,
650 "cost_per_1m_out_cached": 1.1,
651 "context_window": 64000,
652 "default_max_tokens": 5000
653 }
654 ]
655 }
656 }
657}
658```
659
660#### Anthropic-Compatible APIs
661
662Custom Anthropic-compatible providers follow this format:
663
664```json
665{
666 "$schema": "https://charm.land/crush.json",
667 "providers": {
668 "custom-anthropic": {
669 "type": "anthropic",
670 "base_url": "https://api.anthropic.com/v1",
671 "api_key": "$ANTHROPIC_API_KEY",
672 "extra_headers": {
673 "anthropic-version": "2023-06-01"
674 },
675 "models": [
676 {
677 "id": "claude-sonnet-4-20250514",
678 "name": "Claude Sonnet 4",
679 "cost_per_1m_in": 3,
680 "cost_per_1m_out": 15,
681 "cost_per_1m_in_cached": 3.75,
682 "cost_per_1m_out_cached": 0.3,
683 "context_window": 200000,
684 "default_max_tokens": 50000,
685 "can_reason": true,
686 "supports_attachments": true
687 }
688 ]
689 }
690 }
691}
692```
693
694### Amazon Bedrock
695
696Crush currently supports running Anthropic models through Bedrock, with caching disabled.
697
698- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
699- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
700- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
701- Alternatively to `aws configure`, you can also just set `AWS_BEARER_TOKEN_BEDROCK`
702
703### Vertex AI Platform
704
705Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
706
707```bash
708gcloud auth application-default login
709```
710
711To add specific models to the configuration, configure as such:
712
713```json
714{
715 "$schema": "https://charm.land/crush.json",
716 "providers": {
717 "vertexai": {
718 "models": [
719 {
720 "id": "claude-sonnet-4@20250514",
721 "name": "VertexAI Sonnet 4",
722 "cost_per_1m_in": 3,
723 "cost_per_1m_out": 15,
724 "cost_per_1m_in_cached": 3.75,
725 "cost_per_1m_out_cached": 0.3,
726 "context_window": 200000,
727 "default_max_tokens": 50000,
728 "can_reason": true,
729 "supports_attachments": true
730 }
731 ]
732 }
733 }
734}
735```
736
737### Local Models
738
739Local models can also be configured via OpenAI-compatible API. Here are two common examples:
740
741#### Ollama
742
743```json
744{
745 "providers": {
746 "ollama": {
747 "name": "Ollama",
748 "base_url": "http://localhost:11434/v1/",
749 "type": "openai-compat",
750 "models": [
751 {
752 "name": "Qwen 3 30B",
753 "id": "qwen3:30b",
754 "context_window": 256000,
755 "default_max_tokens": 20000
756 }
757 ]
758 }
759 }
760}
761```
762
763#### LM Studio
764
765```json
766{
767 "providers": {
768 "lmstudio": {
769 "name": "LM Studio",
770 "base_url": "http://localhost:1234/v1/",
771 "type": "openai-compat",
772 "models": [
773 {
774 "name": "Qwen 3 30B",
775 "id": "qwen/qwen3-30b-a3b-2507",
776 "context_window": 256000,
777 "default_max_tokens": 20000
778 }
779 ]
780 }
781 }
782}
783```
784
785## Logging
786
787Sometimes you need to look at logs. Luckily, Crush logs all sorts of
788stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
789
790The CLI also contains some helper commands to make perusing recent logs easier:
791
792```bash
793# Print the last 1000 lines
794crush logs
795
796# Print the last 500 lines
797crush logs --tail 500
798
799# Follow logs in real time
800crush logs --follow
801```
802
803Want more logging? Run `crush` with the `--debug` flag, or enable it in the
804config:
805
806```json
807{
808 "$schema": "https://charm.land/crush.json",
809 "options": {
810 "debug": true,
811 "debug_lsp": true
812 }
813}
814```
815
816## Provider Auto-Updates
817
818By default, Crush automatically checks for the latest and greatest list of
819providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
820the open source Crush provider database. This means that when new providers and
821models are available, or when model metadata changes, Crush automatically
822updates your local configuration.
823
824### Disabling automatic provider updates
825
826For those with restricted internet access, or those who prefer to work in
827air-gapped environments, this might not be want you want, and this feature can
828be disabled.
829
830To disable automatic provider updates, set `disable_provider_auto_update` into
831your `crush.json` config:
832
833```json
834{
835 "$schema": "https://charm.land/crush.json",
836 "options": {
837 "disable_provider_auto_update": true
838 }
839}
840```
841
842Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
843
844```bash
845export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
846```
847
848### Manually updating providers
849
850Manually updating providers is possible with the `crush update-providers`
851command:
852
853```bash
854# Update providers remotely from Catwalk.
855crush update-providers
856
857# Update providers from a custom Catwalk base URL.
858crush update-providers https://example.com/
859
860# Update providers from a local file.
861crush update-providers /path/to/local-providers.json
862
863# Reset providers to the embedded version, embedded at crush at build time.
864crush update-providers embedded
865
866# For more info:
867crush update-providers --help
868```
869
870## Metrics
871
872Crush records pseudonymous usage metrics (tied to a device-specific hash),
873which maintainers rely on to inform development and support priorities. The
874metrics include solely usage metadata; prompts and responses are NEVER
875collected.
876
877Details on exactly what’s collected are in the source code ([here](https://github.com/charmbracelet/crush/tree/main/internal/event)
878and [here](https://github.com/charmbracelet/crush/blob/main/internal/llm/agent/event.go)).
879
880You can opt out of metrics collection at any time by setting the environment
881variable by setting the following in your environment:
882
883```bash
884export CRUSH_DISABLE_METRICS=1
885```
886
887Or by setting the following in your config:
888
889```json
890{
891 "options": {
892 "disable_metrics": true
893 }
894}
895```
896
897Crush also respects the [`DO_NOT_TRACK`](https://donottrack.sh/) convention
898which can be enabled via `export DO_NOT_TRACK=1`.
899
900## Q&A
901
902### Why is clipboard copy and paste not working?
903
904Installing an extra tool might be needed on Unix-like environments.
905
906| Environment | Tool |
907| ------------------- | ------------------------ |
908| Windows | Native support |
909| macOS | Native support |
910| Linux/BSD + Wayland | `wl-copy` and `wl-paste` |
911| Linux/BSD + X11 | `xclip` or `xsel` |
912
913## Contributing
914
915See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
916
917## Whatcha think?
918
919We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
920
921- [Twitter](https://twitter.com/charmcli)
922- [Slack][slack]
923- [Discord][discord]
924- [The Fediverse](https://mastodon.social/@charmcli)
925- [Bluesky](https://bsky.app/profile/charm.land)
926
927[slack]: https://charm.land/slack
928[discord]: https://charm.land/discord
929
930## License
931
932[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
933
934---
935
936Part of [Charm](https://charm.land).
937
938<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-softy.jpg" /></a>
939
940<!--prettier-ignore-->
941Charm热爱开源 • Charm loves open source