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#### User-Invocable Skills
529
530Skills can be made invocable as commands from the commands palette (Ctrl+P). Add `user-invocable: true` to the skill's YAML frontmatter:
531
532```yaml
533---
534name: my-skill
535description: A skill that can be invoked as a command.
536user-invocable: true
537---
538```
539
540User-invocable skills appear in the commands palette with a `user:` or `project:` prefix:
541- Skills from global directories show as `user:skill-name`
542- Skills from project directories show as `project:skill-name`
543
544When invoked, the skill's instructions are loaded into the conversation context.
545
546To prevent the model from auto-triggering a skill (while still allowing user invocation), add `disable-model-invocation: true`:
547
548```yaml
549---
550name: my-skill
551description: Only invocable by users, not the model.
552user-invocable: true
553disable-model-invocation: true
554---
555```
556
557Skills with `disable-model-invocation` won't appear in the model's available skills list but can still be invoked manually by users.
558
559### Desktop notifications
560
561Crush sends desktop notifications when a tool call requires permission and when
562the agent finishes its turn. They're only sent when the terminal window isn't
563focused _and_ your terminal supports reporting the focus state.
564
565```jsonc
566{
567 "$schema": "https://charm.land/crush.json",
568 "options": {
569 "disable_notifications": false, // default
570 },
571}
572```
573
574To disable desktop notifications, set `disable_notifications` to `true` in your
575configuration. On macOS, notifications currently lack icons due to platform
576limitations.
577
578### Initialization
579
580When you initialize a project, Crush analyzes your codebase and creates
581a context file that helps it work more effectively in future sessions.
582By default, this file is named `AGENTS.md`, but you can customize the
583name and location with the `initialize_as` option:
584
585```json
586{
587 "$schema": "https://charm.land/crush.json",
588 "options": {
589 "initialize_as": "AGENTS.md"
590 }
591}
592```
593
594This is useful if you prefer a different naming convention or want to
595place the file in a specific directory (e.g., `CRUSH.md` or
596`docs/LLMs.md`). Crush will fill the file with project-specific context
597like build commands, code patterns, and conventions it discovered during
598initialization.
599
600### Attribution Settings
601
602By default, Crush adds attribution information to Git commits and pull requests
603it creates. You can customize this behavior with the `attribution` option:
604
605```json
606{
607 "$schema": "https://charm.land/crush.json",
608 "options": {
609 "attribution": {
610 "trailer_style": "co-authored-by",
611 "generated_with": true
612 }
613 }
614}
615```
616
617- `trailer_style`: Controls the attribution trailer added to commit messages
618 (default: `assisted-by`)
619 - `assisted-by`: Adds `Assisted-by: Crush:[ModelID]` as specified in [the convention](https://docs.kernel.org/process/coding-assistants.html#attribution)
620 - `co-authored-by`: Adds `Co-Authored-By: Crush <crush@charm.land>`
621 - `none`: No attribution trailer
622- `generated_with`: When true (default), adds `💘 Generated with Crush` line to
623 commit messages and PR descriptions
624
625### Custom Providers
626
627Crush supports custom provider configurations for both OpenAI-compatible and
628Anthropic-compatible APIs.
629
630> [!NOTE]
631> Note that we support two "types" for OpenAI. Make sure to choose the right one
632> to ensure the best experience!
633>
634> - `openai` should be used when proxying or routing requests through OpenAI.
635> - `openai-compat` should be used when using non-OpenAI providers that have OpenAI-compatible APIs.
636
637#### OpenAI-Compatible APIs
638
639Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
640API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
641
642```json
643{
644 "$schema": "https://charm.land/crush.json",
645 "providers": {
646 "deepseek": {
647 "type": "openai-compat",
648 "base_url": "https://api.deepseek.com/v1",
649 "api_key": "$DEEPSEEK_API_KEY",
650 "models": [
651 {
652 "id": "deepseek-chat",
653 "name": "Deepseek V3",
654 "cost_per_1m_in": 0.27,
655 "cost_per_1m_out": 1.1,
656 "cost_per_1m_in_cached": 0.07,
657 "cost_per_1m_out_cached": 1.1,
658 "context_window": 64000,
659 "default_max_tokens": 5000
660 }
661 ]
662 }
663 }
664}
665```
666
667#### Anthropic-Compatible APIs
668
669Custom Anthropic-compatible providers follow this format:
670
671```json
672{
673 "$schema": "https://charm.land/crush.json",
674 "providers": {
675 "custom-anthropic": {
676 "type": "anthropic",
677 "base_url": "https://api.anthropic.com/v1",
678 "api_key": "$ANTHROPIC_API_KEY",
679 "extra_headers": {
680 "anthropic-version": "2023-06-01"
681 },
682 "models": [
683 {
684 "id": "claude-sonnet-4-20250514",
685 "name": "Claude Sonnet 4",
686 "cost_per_1m_in": 3,
687 "cost_per_1m_out": 15,
688 "cost_per_1m_in_cached": 3.75,
689 "cost_per_1m_out_cached": 0.3,
690 "context_window": 200000,
691 "default_max_tokens": 50000,
692 "can_reason": true,
693 "supports_attachments": true
694 }
695 ]
696 }
697 }
698}
699```
700
701### Amazon Bedrock
702
703Crush currently supports running Anthropic models through Bedrock, with caching disabled.
704
705- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
706- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
707- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
708- Alternatively to `aws configure`, you can also just set `AWS_BEARER_TOKEN_BEDROCK`
709
710### Vertex AI Platform
711
712Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
713
714```bash
715gcloud auth application-default login
716```
717
718To add specific models to the configuration, configure as such:
719
720```json
721{
722 "$schema": "https://charm.land/crush.json",
723 "providers": {
724 "vertexai": {
725 "models": [
726 {
727 "id": "claude-sonnet-4@20250514",
728 "name": "VertexAI Sonnet 4",
729 "cost_per_1m_in": 3,
730 "cost_per_1m_out": 15,
731 "cost_per_1m_in_cached": 3.75,
732 "cost_per_1m_out_cached": 0.3,
733 "context_window": 200000,
734 "default_max_tokens": 50000,
735 "can_reason": true,
736 "supports_attachments": true
737 }
738 ]
739 }
740 }
741}
742```
743
744### Local Models
745
746Local models can also be configured via OpenAI-compatible API. Here are two common examples:
747
748#### Ollama
749
750```json
751{
752 "providers": {
753 "ollama": {
754 "name": "Ollama",
755 "base_url": "http://localhost:11434/v1/",
756 "type": "openai-compat",
757 "models": [
758 {
759 "name": "Qwen 3 30B",
760 "id": "qwen3:30b",
761 "context_window": 256000,
762 "default_max_tokens": 20000
763 }
764 ]
765 }
766 }
767}
768```
769
770#### LM Studio
771
772```json
773{
774 "providers": {
775 "lmstudio": {
776 "name": "LM Studio",
777 "base_url": "http://localhost:1234/v1/",
778 "type": "openai-compat",
779 "models": [
780 {
781 "name": "Qwen 3 30B",
782 "id": "qwen/qwen3-30b-a3b-2507",
783 "context_window": 256000,
784 "default_max_tokens": 20000
785 }
786 ]
787 }
788 }
789}
790```
791
792## Logging
793
794Sometimes you need to look at logs. Luckily, Crush logs all sorts of
795stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
796
797The CLI also contains some helper commands to make perusing recent logs easier:
798
799```bash
800# Print the last 1000 lines
801crush logs
802
803# Print the last 500 lines
804crush logs --tail 500
805
806# Follow logs in real time
807crush logs --follow
808```
809
810Want more logging? Run `crush` with the `--debug` flag, or enable it in the
811config:
812
813```json
814{
815 "$schema": "https://charm.land/crush.json",
816 "options": {
817 "debug": true,
818 "debug_lsp": true
819 }
820}
821```
822
823## Provider Auto-Updates
824
825By default, Crush automatically checks for the latest and greatest list of
826providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
827the open source Crush provider database. This means that when new providers and
828models are available, or when model metadata changes, Crush automatically
829updates your local configuration.
830
831### Disabling automatic provider updates
832
833For those with restricted internet access, or those who prefer to work in
834air-gapped environments, this might not be want you want, and this feature can
835be disabled.
836
837To disable automatic provider updates, set `disable_provider_auto_update` into
838your `crush.json` config:
839
840```json
841{
842 "$schema": "https://charm.land/crush.json",
843 "options": {
844 "disable_provider_auto_update": true
845 }
846}
847```
848
849Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
850
851```bash
852export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
853```
854
855### Manually updating providers
856
857Manually updating providers is possible with the `crush update-providers`
858command:
859
860```bash
861# Update providers remotely from Catwalk.
862crush update-providers
863
864# Update providers from a custom Catwalk base URL.
865crush update-providers https://example.com/
866
867# Update providers from a local file.
868crush update-providers /path/to/local-providers.json
869
870# Reset providers to the embedded version, embedded at crush at build time.
871crush update-providers embedded
872
873# For more info:
874crush update-providers --help
875```
876
877## Metrics
878
879Crush records pseudonymous usage metrics (tied to a device-specific hash),
880which maintainers rely on to inform development and support priorities. The
881metrics include solely usage metadata; prompts and responses are NEVER
882collected.
883
884Details on exactly what’s collected are in the source code ([here](https://github.com/charmbracelet/crush/tree/main/internal/event)
885and [here](https://github.com/charmbracelet/crush/blob/main/internal/llm/agent/event.go)).
886
887You can opt out of metrics collection at any time by setting the environment
888variable by setting the following in your environment:
889
890```bash
891export CRUSH_DISABLE_METRICS=1
892```
893
894Or by setting the following in your config:
895
896```json
897{
898 "options": {
899 "disable_metrics": true
900 }
901}
902```
903
904Crush also respects the [`DO_NOT_TRACK`](https://donottrack.sh/) convention
905which can be enabled via `export DO_NOT_TRACK=1`.
906
907## Q&A
908
909### Why is clipboard copy and paste not working?
910
911Installing an extra tool might be needed on Unix-like environments.
912
913| Environment | Tool |
914| ------------------- | ------------------------ |
915| Windows | Native support |
916| macOS | Native support |
917| Linux/BSD + Wayland | `wl-copy` and `wl-paste` |
918| Linux/BSD + X11 | `xclip` or `xsel` |
919
920## Contributing
921
922See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
923
924## Whatcha think?
925
926We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
927
928- [Twitter](https://twitter.com/charmcli)
929- [Slack][slack]
930- [Discord][discord]
931- [The Fediverse](https://mastodon.social/@charmcli)
932- [Bluesky](https://bsky.app/profile/charm.land)
933
934[slack]: https://charm.land/slack
935[discord]: https://charm.land/discord
936
937## License
938
939[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
940
941---
942
943Part of [Charm](https://charm.land).
944
945<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-softy.jpg" /></a>
946
947<!--prettier-ignore-->
948Charm热爱开源 • Charm loves open source