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### Sharing a workspace across clients
372
373When Crush is run against a shared backend (for example two TUIs talking to
374the same `crush serve`), clients are grouped into **workspaces** keyed by
375their resolved `--cwd`. Two clients with the same `--cwd` join the same
376underlying workspace, so they share the session list, message history,
377permission queue, LSP, and MCP state.
378
379Joining is implicit: pointing a second client at the same working directory
380attaches it to the existing workspace. Each new invocation, however, starts
381in its own fresh session by default. To pick up the conversation another
382client already has open, use the session manager (the session picker) and
383select it. Sessions surface two signals there:
384
385- `IsBusy` is set while an agent turn is in flight for that session.
386- `AttachedClients` reports how many clients are currently viewing it.
387
388A non-zero `AttachedClients` (often combined with `IsBusy`) is the cue that a
389session is "in progress" on another client and joining it will mirror that
390view live.
391
392The first client to create a workspace fixes its process-wide flags. In
393particular, `--yolo` and `--debug` follow a **first-wins** rule: later
394clients that arrive at the same `--cwd` with different values for those
395flags do not change the running workspace. A debug log line is emitted
396recording the mismatch, and the workspace keeps the flags it was created
397with.
398
399A workspace lives as long as at least one client has an SSE event stream
400open against it. When the last stream disconnects, the workspace is torn
401down. There is a short grace window right after `POST /v1/workspaces` so a
402client that has created the workspace but not yet opened its event stream
403does not get reaped before it can attach.
404
405### Ignoring Files
406
407Crush respects `.gitignore` files by default, but you can also create a
408`.crushignore` file to specify additional files and directories that Crush
409should ignore. This is useful for excluding files that you want in version
410control but don't want Crush to consider when providing context.
411
412The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
413in the root of your project or in subdirectories.
414
415### Allowing Tools
416
417By default, Crush will ask you for permission before running tool calls. If
418you'd like, you can allow tools to be executed without prompting you for
419permissions. Use this with care.
420
421```json
422{
423 "$schema": "https://charm.land/crush.json",
424 "permissions": {
425 "allowed_tools": [
426 "view",
427 "ls",
428 "grep",
429 "edit",
430 "mcp_context7_get-library-doc"
431 ]
432 }
433}
434```
435
436You can also skip all permission prompts entirely by running Crush with the
437`--yolo` flag. Be very, very careful with this feature.
438
439### Disabling Built-In Tools
440
441If you'd like to prevent Crush from using certain built-in tools entirely, you
442can disable them via the `options.disabled_tools` list. Disabled tools are
443completely hidden from the agent.
444
445```json
446{
447 "$schema": "https://charm.land/crush.json",
448 "options": {
449 "disabled_tools": ["bash", "sourcegraph"]
450 }
451}
452```
453
454To disable tools from MCP servers, see the [MCP config section](#mcps).
455
456### Disabling Skills
457
458If you'd like to prevent Crush from using certain skills entirely, you can
459disable them via the `options.disabled_skills` list. Disabled skills are hidden
460from the agent, including builtin skills and skills discovered from disk.
461
462```json
463{
464 "$schema": "https://charm.land/crush.json",
465 "options": {
466 "disabled_skills": ["crush-config"]
467 }
468}
469```
470
471### Agent Skills
472
473Crush supports the [Agent Skills](https://agentskills.io) open standard for
474extending agent capabilities with reusable skill packages. Skills are folders
475containing a `SKILL.md` file with instructions that Crush can discover and
476activate on demand.
477
478The global paths we looks for skills are:
479
480* `$CRUSH_SKILLS_DIR`
481* `$XDG_CONFIG_HOME/agents/skills` or `~/.config/agents/skills/`
482* `$XDG_CONFIG_HOME/crush/skills` or `~/.config/crush/skills/`
483* `~/.agents/skills/`
484* `~/.claude/skills/`
485* On Windows, we _also_ look at
486 * `%LOCALAPPDATA%\agents\skills\` or `%USERPROFILE%\AppData\Local\agents\skills\`
487 * `%LOCALAPPDATA%\crush\skills\` or `%USERPROFILE%\AppData\Local\crush\skills\`
488* Additional paths configured via `options.skills_paths`
489
490On top of that, we _also_ load skills in your project from the following
491relative paths:
492
493* `.agents/skills`
494* `.crush/skills`
495* `.claude/skills`
496* `.cursor/skills`
497
498```jsonc
499{
500 "$schema": "https://charm.land/crush.json",
501 "options": {
502 "skills_paths": [
503 "~/.config/crush/skills", // Windows: "%LOCALAPPDATA%\\crush\\skills",
504 "./project-skills",
505 ],
506 },
507}
508```
509
510You can get started with example skills from [anthropics/skills](https://github.com/anthropics/skills):
511
512```bash
513# Unix
514mkdir -p ~/.config/crush/skills
515cd ~/.config/crush/skills
516git clone https://github.com/anthropics/skills.git _temp
517mv _temp/skills/* . && rm -rf _temp
518```
519
520```powershell
521# Windows (PowerShell)
522mkdir -Force "$env:LOCALAPPDATA\crush\skills"
523cd "$env:LOCALAPPDATA\crush\skills"
524git clone https://github.com/anthropics/skills.git _temp
525mv _temp/skills/* . ; rm -r -force _temp
526```
527
528### Desktop notifications
529
530Crush sends desktop notifications when a tool call requires permission and when
531the agent finishes its turn. They're only sent when the terminal window isn't
532focused _and_ your terminal supports reporting the focus state.
533
534```jsonc
535{
536 "$schema": "https://charm.land/crush.json",
537 "options": {
538 "disable_notifications": false, // default
539 },
540}
541```
542
543To disable desktop notifications, set `disable_notifications` to `true` in your
544configuration. On macOS, notifications currently lack icons due to platform
545limitations.
546
547### Initialization
548
549When you initialize a project, Crush analyzes your codebase and creates
550a context file that helps it work more effectively in future sessions.
551By default, this file is named `AGENTS.md`, but you can customize the
552name and location with the `initialize_as` option:
553
554```json
555{
556 "$schema": "https://charm.land/crush.json",
557 "options": {
558 "initialize_as": "AGENTS.md"
559 }
560}
561```
562
563This is useful if you prefer a different naming convention or want to
564place the file in a specific directory (e.g., `CRUSH.md` or
565`docs/LLMs.md`). Crush will fill the file with project-specific context
566like build commands, code patterns, and conventions it discovered during
567initialization.
568
569### Attribution Settings
570
571By default, Crush adds attribution information to Git commits and pull requests
572it creates. You can customize this behavior with the `attribution` option:
573
574```json
575{
576 "$schema": "https://charm.land/crush.json",
577 "options": {
578 "attribution": {
579 "trailer_style": "co-authored-by",
580 "generated_with": true
581 }
582 }
583}
584```
585
586- `trailer_style`: Controls the attribution trailer added to commit messages
587 (default: `assisted-by`)
588 - `assisted-by`: Adds `Assisted-by: Crush:[ModelID]` as specified in [the convention](https://docs.kernel.org/process/coding-assistants.html#attribution)
589 - `co-authored-by`: Adds `Co-Authored-By: Crush <crush@charm.land>`
590 - `none`: No attribution trailer
591- `generated_with`: When true (default), adds `💘 Generated with Crush` line to
592 commit messages and PR descriptions
593
594### Custom Providers
595
596Crush supports custom provider configurations for both OpenAI-compatible and
597Anthropic-compatible APIs.
598
599> [!NOTE]
600> Note that we support two "types" for OpenAI. Make sure to choose the right one
601> to ensure the best experience!
602>
603> - `openai` should be used when proxying or routing requests through OpenAI.
604> - `openai-compat` should be used when using non-OpenAI providers that have OpenAI-compatible APIs.
605
606#### OpenAI-Compatible APIs
607
608Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
609API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
610
611```json
612{
613 "$schema": "https://charm.land/crush.json",
614 "providers": {
615 "deepseek": {
616 "type": "openai-compat",
617 "base_url": "https://api.deepseek.com/v1",
618 "api_key": "$DEEPSEEK_API_KEY",
619 "models": [
620 {
621 "id": "deepseek-chat",
622 "name": "Deepseek V3",
623 "cost_per_1m_in": 0.27,
624 "cost_per_1m_out": 1.1,
625 "cost_per_1m_in_cached": 0.07,
626 "cost_per_1m_out_cached": 1.1,
627 "context_window": 64000,
628 "default_max_tokens": 5000
629 }
630 ]
631 }
632 }
633}
634```
635
636#### Anthropic-Compatible APIs
637
638Custom Anthropic-compatible providers follow this format:
639
640```json
641{
642 "$schema": "https://charm.land/crush.json",
643 "providers": {
644 "custom-anthropic": {
645 "type": "anthropic",
646 "base_url": "https://api.anthropic.com/v1",
647 "api_key": "$ANTHROPIC_API_KEY",
648 "extra_headers": {
649 "anthropic-version": "2023-06-01"
650 },
651 "models": [
652 {
653 "id": "claude-sonnet-4-20250514",
654 "name": "Claude Sonnet 4",
655 "cost_per_1m_in": 3,
656 "cost_per_1m_out": 15,
657 "cost_per_1m_in_cached": 3.75,
658 "cost_per_1m_out_cached": 0.3,
659 "context_window": 200000,
660 "default_max_tokens": 50000,
661 "can_reason": true,
662 "supports_attachments": true
663 }
664 ]
665 }
666 }
667}
668```
669
670### Amazon Bedrock
671
672Crush currently supports running Anthropic models through Bedrock, with caching disabled.
673
674- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
675- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
676- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
677- Alternatively to `aws configure`, you can also just set `AWS_BEARER_TOKEN_BEDROCK`
678
679### Vertex AI Platform
680
681Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
682
683```bash
684gcloud auth application-default login
685```
686
687To add specific models to the configuration, configure as such:
688
689```json
690{
691 "$schema": "https://charm.land/crush.json",
692 "providers": {
693 "vertexai": {
694 "models": [
695 {
696 "id": "claude-sonnet-4@20250514",
697 "name": "VertexAI Sonnet 4",
698 "cost_per_1m_in": 3,
699 "cost_per_1m_out": 15,
700 "cost_per_1m_in_cached": 3.75,
701 "cost_per_1m_out_cached": 0.3,
702 "context_window": 200000,
703 "default_max_tokens": 50000,
704 "can_reason": true,
705 "supports_attachments": true
706 }
707 ]
708 }
709 }
710}
711```
712
713### Local Models
714
715Local models can also be configured via OpenAI-compatible API. Here are two common examples:
716
717#### Ollama
718
719```json
720{
721 "providers": {
722 "ollama": {
723 "name": "Ollama",
724 "base_url": "http://localhost:11434/v1/",
725 "type": "openai-compat",
726 "models": [
727 {
728 "name": "Qwen 3 30B",
729 "id": "qwen3:30b",
730 "context_window": 256000,
731 "default_max_tokens": 20000
732 }
733 ]
734 }
735 }
736}
737```
738
739#### LM Studio
740
741```json
742{
743 "providers": {
744 "lmstudio": {
745 "name": "LM Studio",
746 "base_url": "http://localhost:1234/v1/",
747 "type": "openai-compat",
748 "models": [
749 {
750 "name": "Qwen 3 30B",
751 "id": "qwen/qwen3-30b-a3b-2507",
752 "context_window": 256000,
753 "default_max_tokens": 20000
754 }
755 ]
756 }
757 }
758}
759```
760
761## Logging
762
763Sometimes you need to look at logs. Luckily, Crush logs all sorts of
764stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
765
766The CLI also contains some helper commands to make perusing recent logs easier:
767
768```bash
769# Print the last 1000 lines
770crush logs
771
772# Print the last 500 lines
773crush logs --tail 500
774
775# Follow logs in real time
776crush logs --follow
777```
778
779Want more logging? Run `crush` with the `--debug` flag, or enable it in the
780config:
781
782```json
783{
784 "$schema": "https://charm.land/crush.json",
785 "options": {
786 "debug": true,
787 "debug_lsp": true
788 }
789}
790```
791
792## Provider Auto-Updates
793
794By default, Crush automatically checks for the latest and greatest list of
795providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
796the open source Crush provider database. This means that when new providers and
797models are available, or when model metadata changes, Crush automatically
798updates your local configuration.
799
800### Disabling automatic provider updates
801
802For those with restricted internet access, or those who prefer to work in
803air-gapped environments, this might not be want you want, and this feature can
804be disabled.
805
806To disable automatic provider updates, set `disable_provider_auto_update` into
807your `crush.json` config:
808
809```json
810{
811 "$schema": "https://charm.land/crush.json",
812 "options": {
813 "disable_provider_auto_update": true
814 }
815}
816```
817
818Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
819
820```bash
821export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
822```
823
824### Manually updating providers
825
826Manually updating providers is possible with the `crush update-providers`
827command:
828
829```bash
830# Update providers remotely from Catwalk.
831crush update-providers
832
833# Update providers from a custom Catwalk base URL.
834crush update-providers https://example.com/
835
836# Update providers from a local file.
837crush update-providers /path/to/local-providers.json
838
839# Reset providers to the embedded version, embedded at crush at build time.
840crush update-providers embedded
841
842# For more info:
843crush update-providers --help
844```
845
846## Metrics
847
848Crush records pseudonymous usage metrics (tied to a device-specific hash),
849which maintainers rely on to inform development and support priorities. The
850metrics include solely usage metadata; prompts and responses are NEVER
851collected.
852
853Details on exactly what’s collected are in the source code ([here](https://github.com/charmbracelet/crush/tree/main/internal/event)
854and [here](https://github.com/charmbracelet/crush/blob/main/internal/llm/agent/event.go)).
855
856You can opt out of metrics collection at any time by setting the environment
857variable by setting the following in your environment:
858
859```bash
860export CRUSH_DISABLE_METRICS=1
861```
862
863Or by setting the following in your config:
864
865```json
866{
867 "options": {
868 "disable_metrics": true
869 }
870}
871```
872
873Crush also respects the [`DO_NOT_TRACK`](https://donottrack.sh/) convention
874which can be enabled via `export DO_NOT_TRACK=1`.
875
876## Q&A
877
878### Why is clipboard copy and paste not working?
879
880Installing an extra tool might be needed on Unix-like environments.
881
882| Environment | Tool |
883| ------------------- | ------------------------ |
884| Windows | Native support |
885| macOS | Native support |
886| Linux/BSD + Wayland | `wl-copy` and `wl-paste` |
887| Linux/BSD + X11 | `xclip` or `xsel` |
888
889## Contributing
890
891See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
892
893## Whatcha think?
894
895We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
896
897- [Twitter](https://twitter.com/charmcli)
898- [Slack][slack]
899- [Discord][discord]
900- [The Fediverse](https://mastodon.social/@charmcli)
901- [Bluesky](https://bsky.app/profile/charm.land)
902
903[slack]: https://charm.land/slack
904[discord]: https://charm.land/discord
905
906## License
907
908[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
909
910---
911
912Part of [Charm](https://charm.land).
913
914<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-softy.jpg" /></a>
915
916<!--prettier-ignore-->
917Charm热爱开源 • Charm loves open source