1**NOTE:** This is a personal fork of
2[Crush](https://github.com/charmbracelet/crush) fork where I'm
3experimenting with prompts and other things. You'll also find my patches
4merged here before they're merged into upstream. Additionally, I've yote
5the CLA; devs shouldn't assign their copyrights to maintainers and hand
6them the rug they'll yank from under you later.
7
8Install my fork either…
9- Using [bin](https://github.com/marcosnils/bin) (highly recommended
10 because it's one tool to manage and update myriad CLI tools
11 distributed as statically-linked binaries, like _nasin pali_)
12 ```bash
13 bin install goinstall://git.secluded.site/crush@latest
14 ```
15- Or using the [go toolchain](https://go.dev/dl) (requires tracking updates
16 manually)
17 ```bash
18 go install git.secluded.site/crush@latest
19 ```
20
21I pull upstream changes into the `upstream` branch here, break my
22branches off that, then merge them into my `dev` branch, which gets
23rebased on `upstream` fairly often. `dev` history will get rewritten
24frequently.
25
26Contributions are welcome (see following section) and I'll try to
27maintain anything I accept here.
28
29## Contributions
30
31Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't
32need a new account to contribute, you don't need to fork this repo, you
33don't need to fiddle with `git send-email`, you don't need to faff with
34your email client to get `git request-pull` working...
35
36You just need:
37
38- Git
39- SSH
40- An SSH key
41
42```sh
43# Clone this repo, make your changes, and commit them
44# Create a new patch request with
45git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
46# After potential feedback, submit a revision to an existing patch request with
47git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
48# List patch requests
49ssh pr.pico.sh pr ls amolith/llm-projects
50```
51
52See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
53complete example workflow.
54
55[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
56[pr.pico.sh]: https://pr.pico.sh
57
58---
59
60_Everything from here on is from the original Crush README._
61
62---
63
64# Crush
65
66<p align="center">
67 <a href="https://stuff.charm.sh/crush/charm-crush.png"><img width="450" alt="Charm Crush Logo" src="https://github.com/user-attachments/assets/adc1a6f4-b284-4603-836c-59038caa2e8b" /></a><br />
68 <a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>
69 <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>
70</p>
71
72<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>
73<p align="center">你的新编程伙伴，现在就在你最爱的终端中。<br />你的工具、代码和工作流，都与您选择的 LLM 模型紧密相连。</p>
74
75<p align="center"><img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/58280caf-851b-470a-b6f7-d5c4ea8a1968" /></p>
76
77## Features
78
79- **Multi-Model:** choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
80- **Flexible:** switch LLMs mid-session while preserving context
81- **Session-Based:** maintain multiple work sessions and contexts per project
82- **LSP-Enhanced:** Crush uses LSPs for additional context, just like you do
83- **Extensible:** add capabilities via MCPs (`http`, `stdio`, and `sse`)
84- **Works Everywhere:** first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), FreeBSD, OpenBSD, and NetBSD
85
86## Installation
87
88Use a package manager:
89
90```bash
91# Homebrew
92brew install charmbracelet/tap/crush
93
94# NPM
95npm install -g @charmland/crush
96
97# Arch Linux (btw)
98yay -S crush-bin
99
100# Nix
101nix run github:numtide/nix-ai-tools#crush
102```
103
104Windows users:
105
106```bash
107# Winget
108winget install charmbracelet.crush
109
110# Scoop
111scoop bucket add charm https://github.com/charmbracelet/scoop-bucket.git
112scoop install crush
113```
114
115<details>
116<summary><strong>Nix (NUR)</strong></summary>
117
118Crush is available via [NUR](https://github.com/nix-community/NUR) in `nur.repos.charmbracelet.crush`.
119
120You can also try out Crush via `nix-shell`:
121
122```bash
123# Add the NUR channel.
124nix-channel --add https://github.com/nix-community/NUR/archive/main.tar.gz nur
125nix-channel --update
126
127# Get Crush in a Nix shell.
128nix-shell -p '(import <nur> { pkgs = import <nixpkgs> {}; }).repos.charmbracelet.crush'
129```
130
131### NixOS & Home Manager Module Usage via NUR
132
133Crush provides NixOS and Home Manager modules via NUR.
134You 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 :)
135
136```nix
137{
138 inputs = {
139 nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
140 nur.url = "github:nix-community/NUR";
141 };
142
143 outputs = { self, nixpkgs, nur, ... }: {
144 nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
145 system = "x86_64-linux";
146 modules = [
147 nur.modules.nixos.default
148 nur.repos.charmbracelet.modules.crush
149 {
150 programs.crush = {
151 enable = true;
152 settings = {
153 providers = {
154 openai = {
155 id = "openai";
156 name = "OpenAI";
157 base_url = "https://api.openai.com/v1";
158 type = "openai";
159 api_key = "sk-fake123456789abcdef...";
160 models = [
161 {
162 id = "gpt-4";
163 name = "GPT-4";
164 }
165 ];
166 };
167 };
168 lsp = {
169 go = { command = "gopls"; enabled = true; };
170 nix = { command = "nil"; enabled = true; };
171 };
172 options = {
173 context_paths = [ "/etc/nixos/configuration.nix" ];
174 tui = { compact_mode = true; };
175 debug = false;
176 };
177 };
178 };
179 }
180 ];
181 };
182 };
183}
184```
185
186</details>
187
188<details>
189<summary><strong>Debian/Ubuntu</strong></summary>
190
191```bash
192sudo mkdir -p /etc/apt/keyrings
193curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
194echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
195sudo apt update && sudo apt install crush
196```
197
198</details>
199
200<details>
201<summary><strong>Fedora/RHEL</strong></summary>
202
203```bash
204echo '[charm]
205name=Charm
206baseurl=https://repo.charm.sh/yum/
207enabled=1
208gpgcheck=1
209gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
210sudo yum install crush
211```
212
213</details>
214
215Or, download it:
216
217- [Packages][releases] are available in Debian and RPM formats
218- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
219
220[releases]: https://github.com/charmbracelet/crush/releases
221
222Or just install it with Go:
223
224```
225go install github.com/charmbracelet/crush@latest
226```
227
228> [!WARNING]
229> Productivity may increase when using Crush and you may find yourself nerd
230> sniped when first using the application. If the symptoms persist, join the
231> [Discord][discord] and nerd snipe the rest of us.
232
233## Getting Started
234
235The quickest way to get started is to grab an API key for your preferred
236provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
237Crush. You'll be prompted to enter your API key.
238
239That said, you can also set environment variables for preferred providers.
240
241| Environment Variable | Provider |
242| --------------------------- | -------------------------------------------------- |
243| `ANTHROPIC_API_KEY` | Anthropic |
244| `OPENAI_API_KEY` | OpenAI |
245| `OPENROUTER_API_KEY` | OpenRouter |
246| `GEMINI_API_KEY` | Google Gemini |
247| `CEREBRAS_API_KEY` | Cerebras |
248| `HF_TOKEN` | Huggingface Inference |
249| `VERTEXAI_PROJECT` | Google Cloud VertexAI (Gemini) |
250| `VERTEXAI_LOCATION` | Google Cloud VertexAI (Gemini) |
251| `GROQ_API_KEY` | Groq |
252| `AWS_ACCESS_KEY_ID` | AWS Bedrock (Claude) |
253| `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (Claude) |
254| `AWS_REGION` | AWS Bedrock (Claude) |
255| `AWS_PROFILE` | AWS Bedrock (Custom Profile) |
256| `AWS_BEARER_TOKEN_BEDROCK` | AWS Bedrock |
257| `AZURE_OPENAI_API_ENDPOINT` | Azure OpenAI models |
258| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
259| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
260
261### By the Way
262
263Is there a provider you’d like to see in Crush? Is there an existing model that needs an update?
264
265Crush’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.
266
267<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>
268
269## Configuration
270
271Crush runs great with no configuration. That said, if you do need or want to
272customize Crush, configuration can be added either local to the project itself,
273or globally, with the following priority:
274
2751. `.crush.json`
2762. `crush.json`
2773. `$HOME/.config/crush/crush.json` (Windows: `%USERPROFILE%\AppData\Local\crush\crush.json`)
278
279Configuration itself is stored as a JSON object:
280
281```json
282{
283 "this-setting": { "this": "that" },
284 "that-setting": ["ceci", "cela"]
285}
286```
287
288As an additional note, Crush also stores ephemeral data, such as application state, in one additional location:
289
290```bash
291# Unix
292$HOME/.local/share/crush/crush.json
293
294# Windows
295%LOCALAPPDATA%\crush\crush.json
296```
297
298### LSPs
299
300Crush can use LSPs for additional context to help inform its decisions, just
301like you would. LSPs can be added manually like so:
302
303```json
304{
305 "$schema": "https://charm.land/crush.json",
306 "lsp": {
307 "go": {
308 "command": "gopls",
309 "env": {
310 "GOTOOLCHAIN": "go1.24.5"
311 }
312 },
313 "typescript": {
314 "command": "typescript-language-server",
315 "args": ["--stdio"]
316 },
317 "nix": {
318 "command": "nil"
319 }
320 }
321}
322```
323
324### MCPs
325
326Crush also supports Model Context Protocol (MCP) servers through three
327transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
328and `sse` for Server-Sent Events. Environment variable expansion is supported
329using `$(echo $VAR)` syntax.
330
331```json
332{
333 "$schema": "https://charm.land/crush.json",
334 "mcp": {
335 "filesystem": {
336 "type": "stdio",
337 "command": "node",
338 "args": ["/path/to/mcp-server.js"],
339 "timeout": 120,
340 "disabled": false,
341 "env": {
342 "NODE_ENV": "production"
343 }
344 },
345 "github": {
346 "type": "http",
347 "url": "https://example.com/mcp/",
348 "timeout": 120,
349 "disabled": false,
350 "headers": {
351 "Authorization": "$(echo Bearer $EXAMPLE_MCP_TOKEN)"
352 }
353 },
354 "streaming-service": {
355 "type": "sse",
356 "url": "https://example.com/mcp/sse",
357 "timeout": 120,
358 "disabled": false,
359 "headers": {
360 "API-Key": "$(echo $API_KEY)"
361 }
362 }
363 }
364}
365```
366
367### Memory
368
369Crush automatically includes two memory files for cross-project instructions.
370
371- `~/.config/crush/CRUSH.md`: Crush-specific rules that would confuse other
372 agentic coding tools. If you only use Crush, this is the only one you need to
373 edit.
374- `~/.config/AGENTS.md`: generic instructions that other coding tools might
375 read. Avoid referring to Crush-specific tools or workflows here.
376
377You can customize these paths using the `memory_paths` option in your
378configuration:
379
380```json
381{
382 "$schema": "https://charm.land/crush.json",
383 "options": {
384 "memory_paths": [
385 "/path/to/custom/memory/file.md",
386 "/path/to/folder/of/files/" // recursively load all .md files in folder
387 ]
388 }
389}
390```
391
392### Ignoring Files
393
394Crush respects `.gitignore` files by default, but you can also create a
395`.crushignore` file to specify additional files and directories that Crush
396should ignore. This is useful for excluding files that you want in version
397control but don't want Crush to consider when providing context.
398
399The `.crushignore` file uses the same syntax as `.gitignore` and can be placed
400in the root of your project or in subdirectories.
401
402### Allowing Tools
403
404By default, Crush will ask you for permission before running tool calls. If
405you'd like, you can allow tools to be executed without prompting you for
406permissions. Use this with care.
407
408```json
409{
410 "$schema": "https://charm.land/crush.json",
411 "permissions": {
412 "allowed_tools": [
413 "view",
414 "ls",
415 "grep",
416 "edit",
417 "mcp_context7_get-library-doc"
418 ]
419 }
420}
421```
422
423You can also skip all permission prompts entirely by running Crush with the
424`--yolo` flag. Be very, very careful with this feature.
425
426### Attribution Settings
427
428By default, Crush adds attribution information to Git commits and pull requests
429it creates. You can customize this behavior with the `attribution` option:
430
431```json
432{
433 "$schema": "https://charm.land/crush.json",
434 "options": {
435 "attribution": {
436 "co_authored_by": true,
437 "generated_with": true
438 }
439 }
440}
441```
442
443- `co_authored_by`: When true (default), adds `Co-Authored-By: Crush <crush@charm.land>` to commit messages
444- `generated_with`: When true (default), adds `💘 Generated with Crush` line to commit messages and PR descriptions
445
446### Local Models
447
448Local models can also be configured via OpenAI-compatible API. Here are two common examples:
449
450#### Ollama
451
452```json
453{
454 "providers": {
455 "ollama": {
456 "name": "Ollama",
457 "base_url": "http://localhost:11434/v1/",
458 "type": "openai-compat",
459 "models": [
460 {
461 "name": "Qwen 3 30B",
462 "id": "qwen3:30b",
463 "context_window": 256000,
464 "default_max_tokens": 20000
465 }
466 ]
467 }
468 }
469}
470```
471
472#### LM Studio
473
474```json
475{
476 "providers": {
477 "lmstudio": {
478 "name": "LM Studio",
479 "base_url": "http://localhost:1234/v1/",
480 "type": "openai-compat",
481 "models": [
482 {
483 "name": "Qwen 3 30B",
484 "id": "qwen/qwen3-30b-a3b-2507",
485 "context_window": 256000,
486 "default_max_tokens": 20000
487 }
488 ]
489 }
490 }
491}
492```
493
494### Custom Providers
495
496Crush supports custom provider configurations for both OpenAI-compatible and
497Anthropic-compatible APIs.
498
499> [!NOTE]
500> Note that we support two "types" for OpenAI. Make sure to choose the right one
501> to ensure the best experience!
502> * `openai` should be used when proxying or routing requests through OpenAI.
503> * `openai-compat` should be used when using non-OpenAI providers that have OpenAI-compatible APIs.
504
505#### OpenAI-Compatible APIs
506
507Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
508API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
509
510```json
511{
512 "$schema": "https://charm.land/crush.json",
513 "providers": {
514 "deepseek": {
515 "type": "openai-compat",
516 "base_url": "https://api.deepseek.com/v1",
517 "api_key": "$DEEPSEEK_API_KEY",
518 "models": [
519 {
520 "id": "deepseek-chat",
521 "name": "Deepseek V3",
522 "cost_per_1m_in": 0.27,
523 "cost_per_1m_out": 1.1,
524 "cost_per_1m_in_cached": 0.07,
525 "cost_per_1m_out_cached": 1.1,
526 "context_window": 64000,
527 "default_max_tokens": 5000
528 }
529 ]
530 }
531 }
532}
533```
534
535#### Anthropic-Compatible APIs
536
537Custom Anthropic-compatible providers follow this format:
538
539```json
540{
541 "$schema": "https://charm.land/crush.json",
542 "providers": {
543 "custom-anthropic": {
544 "type": "anthropic",
545 "base_url": "https://api.anthropic.com/v1",
546 "api_key": "$ANTHROPIC_API_KEY",
547 "extra_headers": {
548 "anthropic-version": "2023-06-01"
549 },
550 "models": [
551 {
552 "id": "claude-sonnet-4-20250514",
553 "name": "Claude Sonnet 4",
554 "cost_per_1m_in": 3,
555 "cost_per_1m_out": 15,
556 "cost_per_1m_in_cached": 3.75,
557 "cost_per_1m_out_cached": 0.3,
558 "context_window": 200000,
559 "default_max_tokens": 50000,
560 "can_reason": true,
561 "supports_attachments": true
562 }
563 ]
564 }
565 }
566}
567```
568
569### Amazon Bedrock
570
571Crush currently supports running Anthropic models through Bedrock, with caching disabled.
572
573- A Bedrock provider will appear once you have AWS configured, i.e. `aws configure`
574- Crush also expects the `AWS_REGION` or `AWS_DEFAULT_REGION` to be set
575- To use a specific AWS profile set `AWS_PROFILE` in your environment, i.e. `AWS_PROFILE=myprofile crush`
576- Alternatively to `aws configure`, you can also just set `AWS_BEARER_TOKEN_BEDROCK`
577
578### Vertex AI Platform
579
580Vertex AI will appear in the list of available providers when `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` are set. You will also need to be authenticated:
581
582```bash
583gcloud auth application-default login
584```
585
586To add specific models to the configuration, configure as such:
587
588```json
589{
590 "$schema": "https://charm.land/crush.json",
591 "providers": {
592 "vertexai": {
593 "models": [
594 {
595 "id": "claude-sonnet-4@20250514",
596 "name": "VertexAI Sonnet 4",
597 "cost_per_1m_in": 3,
598 "cost_per_1m_out": 15,
599 "cost_per_1m_in_cached": 3.75,
600 "cost_per_1m_out_cached": 0.3,
601 "context_window": 200000,
602 "default_max_tokens": 50000,
603 "can_reason": true,
604 "supports_attachments": true
605 }
606 ]
607 }
608 }
609}
610```
611
612## Logging
613
614Sometimes you need to look at logs. Luckily, Crush logs all sorts of
615stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
616
617The CLI also contains some helper commands to make perusing recent logs easier:
618
619```bash
620# Print the last 1000 lines
621crush logs
622
623# Print the last 500 lines
624crush logs --tail 500
625
626# Follow logs in real time
627crush logs --follow
628```
629
630Want more logging? Run `crush` with the `--debug` flag, or enable it in the
631config:
632
633```json
634{
635 "$schema": "https://charm.land/crush.json",
636 "options": {
637 "debug": true,
638 "debug_lsp": true
639 }
640}
641```
642
643## Provider Auto-Updates
644
645By default, Crush automatically checks for the latest and greatest list of
646providers and models from [Catwalk](https://github.com/charmbracelet/catwalk),
647the open source Crush provider database. This means that when new providers and
648models are available, or when model metadata changes, Crush automatically
649updates your local configuration.
650
651### Disabling automatic provider updates
652
653For those with restricted internet access, or those who prefer to work in
654air-gapped environments, this might not be want you want, and this feature can
655be disabled.
656
657To disable automatic provider updates, set `disable_provider_auto_update` into
658your `crush.json` config:
659
660```json
661{
662 "$schema": "https://charm.land/crush.json",
663 "options": {
664 "disable_provider_auto_update": true
665 }
666}
667```
668
669Or set the `CRUSH_DISABLE_PROVIDER_AUTO_UPDATE` environment variable:
670
671```bash
672export CRUSH_DISABLE_PROVIDER_AUTO_UPDATE=1
673```
674
675### Manually updating providers
676
677Manually updating providers is possible with the `crush update-providers`
678command:
679
680```bash
681# Update providers remotely from Catwalk.
682crush update-providers
683
684# Update providers from a custom Catwalk base URL.
685crush update-providers https://example.com/
686
687# Update providers from a local file.
688crush update-providers /path/to/local-providers.json
689
690# Reset providers to the embedded version, embedded at crush at build time.
691crush update-providers embedded
692
693# For more info:
694crush update-providers --help
695```
696
697## Metrics
698
699Crush records pseudonymous usage metrics (tied to a device-specific hash),
700which maintainers rely on to inform development and support priorities. The
701metrics include solely usage metadata; prompts and responses are NEVER
702collected.
703
704Details on exactly what’s collected are in the source code ([here](https://github.com/charmbracelet/crush/tree/main/internal/event)
705and [here](https://github.com/charmbracelet/crush/blob/main/internal/llm/agent/event.go)).
706
707You can opt out of metrics collection at any time by setting the environment
708variable by setting the following in your environment:
709
710```bash
711export CRUSH_DISABLE_METRICS=1
712```
713
714Or by setting the following in your config:
715
716```json
717{
718 "options": {
719 "disable_metrics": true
720 }
721}
722```
723
724Crush also respects the [`DO_NOT_TRACK`](https://consoledonottrack.com)
725convention which can be enabled via `export DO_NOT_TRACK=1`.
726
727## A Note on Claude Max and GitHub Copilot
728
729Crush only supports model providers through official, compliant APIs. We do not
730support or endorse any methods that rely on personal Claude Max and GitHub
731Copilot accounts or OAuth workarounds, which violate Anthropic and
732Microsoft’s Terms of Service.
733
734We’re committed to building sustainable, trusted integrations with model
735providers. If you’re a provider interested in working with us,
736[reach out](mailto:vt100@charm.sh).
737
738## Contributing
739
740See the [contributing guide](https://github.com/charmbracelet/crush?tab=contributing-ov-file#contributing).
741
742## Whatcha think?
743
744We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:
745
746- [Twitter](https://twitter.com/charmcli)
747- [Slack](https://charm.land/slack)
748- [Discord][discord]
749- [The Fediverse](https://mastodon.social/@charmcli)
750- [Bluesky](https://bsky.app/profile/charm.land)
751
752[discord]: https://charm.land/discord
753
754## License
755
756[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE.md)
757
758---
759
760Part of [Charm](https://charm.land).
761
762<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
763
764<!--prettier-ignore-->
765Charm热爱开源 • Charm loves open source