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