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