alihan/crush-code-agent-ide
1
0
Fork 0
mirror of https://github.com/charmbracelet/crush.git synced 2025-08-02 05:20:46 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(readme): general update

Browse Source
This commit is contained in:
Christian Rocha
2025-07-28 22:11:53 -04:00
committed by GitHub
parent 4cc1468dd7
commit 05e1927df9
1 changed files with 151 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
README.md
View File

@@ -1,60 +1,101 @@
> [!WARNING]
> 🚧 This is a pre-release under heavy, active development. Things are still in flux but we’re excited to share early progress.
# Crush
<p>
<img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/9ab4c30c-9327-46b6-a722-3ad0e20f6976" /><br>
<img width="450" alt="Charm Crush Art" src="https://github.com/user-attachments/assets/4cd517be-476b-4a78-971c-810a0b1af3f6" /><br>
<a href="https://github.com/charmbracelet/crush/releases"><img src="https://img.shields.io/github/release/charmbracelet/crush" alt="Latest Release"></a>
<a href="https://github.com/charmbracelet/crush/actions"><img src="https://github.com/charmbracelet/crush/workflows/build/badge.svg" alt="Build Status"></a>
</p>
Crush is a tool for building software with AI.
Your new coding bestie, available in your favourite terminal. Your tools, your
code, and your workflows, wired into your LLM of choice.
<img width="800" alt="Crush Demo" src="https://github.com/user-attachments/assets/a67e22a5-167f-4aa0-bcbf-4248740b6fd4" />
## Features
- **Multi-Model:** choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
- **Flexible:** switch LLMs mid-session while preserving context
- **Session-Based:** maintain multiple work sessions and contexts per project
- **LSP-Enhanced:** Crush uses LSPs for additional context, just like you do
- **Extensible:** add capabilities via MCPs (`http`, `stdio`, and `sse`)
- **Works Everywhere:** first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), and FreeBSD
## Installation
Crush has first class support for macOS, Linux, and Windows.
Use a package manager:
Nightly builds are available while Crush is in development.
```bash
# macOS or Linux
brew install charmbracelet/tap/crush
- [Packages](https://github.com/charmbracelet/crush/releases/tag/nightly) are available in Debian, RPM, APK, and PKG formats
- [Binaries](https://github.com/charmbracelet/crush/releases/tag/nightly) are available for Linux, macOS and Windows
# NPM
npm install -g @charmland/crush
You can also just install it with go:
# Arch Linux (btw)
yay -S crush-bin
```
git clone git@github.com:charmbracelet/crush.git
cd crush
go install
# Windows (with Winget)
winget install charmbracelet.crush
# Nix
nix-shell -p nur.repos.charmbracelet.crush
```
<details>
<summary>Not a developer? Here’s a quick how-to.</summary>
Download the latest [nightly release](https://github.com/charmbracelet/crush/releases) for your system. The [macOS ARM64 one](https://github.com/charmbracelet/crush/releases/download/nightly/crush_0.1.0-nightly_Darwin_arm64.tar.gz) is most likely what you want.
Next, open a terminal and run the following commands:
<summary><strong>Debian/Ubuntu</strong></summary>
```bash
cd ~/Downloads
tar -xvzf crush_0.1.0-nightly_Darwin_arm64.tar.gz -C crush
sudo mv ./crush/crush /usr/local/bin/crush
rm -rf ./crush
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install crush
```
Then, run Crush by typing `crush`.
---
</details>
<details>
<summary><strong>Fedora/RHEL</strong></summary>
```bash
echo '[charm]
name=Charm
baseurl=https://repo.charm.sh/yum/
enabled=1
gpgcheck=1
gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
sudo yum install crush
```
</details>
Or, download it:
- [Packages][releases] are available in Debian and RPM formats
- [Binaries][releases] are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD
[releases]: https://github.com/charmbracelet/crush/releases
Or just install it with go:
```
go install github.com/charmbracelet/crush@latest
```
> [!WARNING]
> Productivity may increase when using Crush and you may find yourself nerd
> sniped when first using the application. If the symptoms persist, join the
> [Discord][discord] and nerd snipe the rest of us.
## Getting Started
The quickest way to get started to grab an API key for your preferred
provider such as Anthropic, OpenAI, or Groq, and just start Crush. You'll be
prompted to enter your API key.
The quickest way to get started is to grab an API key for your preferred
provider such as Anthropic, OpenAI, Groq, or OpenRouter and just start
Crush. You'll be prompted to enter your API key.
That said, you can also set environment variables for preferred providers:
That said, you can also set environment variables for preferred providers.
<details>
<summary><strong>Supported Environment Variables</strong></summary>
| Environment Variable | Provider |
| -------------------------- | -------------------------------------------------- |
@@ -71,17 +112,31 @@ That said, you can also set environment variables for preferred providers:
| `AZURE_OPENAI_API_KEY` | Azure OpenAI models (optional when using Entra ID) |
| `AZURE_OPENAI_API_VERSION` | Azure OpenAI models |
</details>
## Configuration
For many use cases, Crush can be run with no config. That said, if you do need config, it can be added either local to the project itself, or globally. Configuration has the following priority:
Crush runs great with no configuration. That said, if you do need or want to
customize Crush, configuration can be added either local to the project itself,
or globally, with the following priority:
1. `.crush.json`
2. `crush.json`
1. `./.crush.json`
2. `./crush.json`
3. `$HOME/.config/crush/crush.json`
Configuration itself is stored as a JSON object:
```json
{
"this-setting": { }
"that-setting": { }
}
```
### LSPs
Crush can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:
Crush can use LSPs for additional context to help inform its decisions, just
like you would. LSPs can be added manually like so:
```json
{
@@ -94,7 +149,7 @@ Crush can use LSPs for additional context to help inform its decisions, just lik
"args": ["--stdio"]
},
"nix": {
"command": "alejandra"
"command": "nil"
}
}
}
@@ -102,7 +157,10 @@ Crush can use LSPs for additional context to help inform its decisions, just lik
### MCPs
Crush supports Model Context Protocol (MCP) servers through three transport types: `stdio` for command-line servers, `http` for HTTP endpoints, and `sse` for Server-Sent Events. Environment variable expansion is supported using `$(echo $VAR)` syntax.
Crush also supports Model Context Protocol (MCP) servers through three
transport types: `stdio` for command-line servers, `http` for HTTP endpoints,
and `sse` for Server-Sent Events. Environment variable expansion is supported
using `$(echo $VAR)` syntax.
```json
{
@@ -133,37 +191,11 @@ Crush supports Model Context Protocol (MCP) servers through three transport type
}
```
### Logging
### Whitelisting Tools
Enable debug logging with the `-d` flag or in config. View logs with `crush logs`. Logs are stored in `.crush/logs/crush.log`.
```bash
# Run with debug logging
crush -d
# View last 1000 lines
crush logs
# Follow logs in real-time
crush logs -f
# Show last 500 lines
crush logs -t 500
```
Add to your `crush.json` config file:
```json
{
"options": {
"debug": true,
"debug_lsp": true
}
}
```
### Configurable Default Permissions
Crush includes a permission system to control which tools can be executed without prompting. You can configure allowed tools in your `crush.json` config file:
By default, Crush will ask you for permission before running tool calls. If
you'd like, you can whitelist tools to be executed without prompting you for
permissions. Use this with care.
```json
{
@@ -172,27 +204,25 @@ Crush includes a permission system to control which tools can be executed withou
"view",
"ls",
"grep",
"edit:write",
"edit",
"mcp_context7_get-library-doc"
]
}
}
```
The `allowed_tools` array accepts:
- Tool names (e.g., `"view"`) - allows all actions for that tool
- Tool:action combinations (e.g., `"edit:write"`) - allows only specific actions
You can also skip all permission prompts entirely by running Crush with the `--yolo` flag.
You can also skip all permission prompts entirely by running Crush with the
`--yolo` flag. Be very, very careful with this feature.
### Custom Providers
Crush supports custom provider configurations for both OpenAI-compatible and Anthropic-compatible APIs.
Crush supports custom provider configurations for both OpenAI-compatible and
Anthropic-compatible APIs.
#### OpenAI-Compatible APIs
Here's an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
Here’s an example configuration for Deepseek, which uses an OpenAI-compatible
API. Don't forget to set `DEEPSEEK_API_KEY` in your environment.
```json
{
@@ -220,7 +250,7 @@ Here's an example configuration for Deepseek, which uses an OpenAI-compatible AP
#### Anthropic-Compatible APIs
You can also configure custom Anthropic-compatible providers:
Custom Anthropic-compatible providers follow this format:
```json
{
@@ -234,14 +264,15 @@ You can also configure custom Anthropic-compatible providers:
},
"models": [
{
"id": "claude-3-sonnet",
"model": "Claude 3 Sonnet",
"cost_per_1m_in": 3000,
"cost_per_1m_out": 15000,
"cost_per_1m_in_cached": 300,
"cost_per_1m_out_cached": 15000,
"id": "claude-sonnet-4-20250514",
"name": "Claude Sonnet 4",
"cost_per_1m_in": 3,
"cost_per_1m_out": 15,
"cost_per_1m_in_cached": 3.75,
"cost_per_1m_out_cached": 0.3,
"context_window": 200000,
"default_max_tokens": 4096,
"default_max_tokens": 50000,
"can_reason": true,
"supports_attachments": true
}
]
@@ -250,23 +281,56 @@ You can also configure custom Anthropic-compatible providers:
}
```
## Logging
Sometimes you need to look at logs. Luckily, Crush logs all sorts of
stuff. Logs are stored in `./.crush/logs/crush.log` relative to the project.
The CLI also contains some helper commands to make perusing recent logs easier:
```bash
# Print the last 1000 lines
crush logs
# Print the last 500 lines
crush logs --tail 500
# Follow logs in real time
crush logs --follow
```
Want more logging? Run `crush` with the `--debug` flag, or enable it in the
config:
```json
{
"options": {
"debug": true,
"debug_lsp": true
}
}
```
## Whatcha think?
We’d love to hear your thoughts on this project. Feel free to drop us a note!
- [Twitter](https://twitter.com/charmcli)
- [Discord][discord]
- [Slack](https://charm.land/slack)
- [The Fediverse](https://mastodon.social/@charmcli)
- [Discord](https://charm.sh/chat)
[discord]: https://charm.land/discord
## License
[MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
[FSL-1.1-MIT](https://github.com/charmbracelet/crush/raw/main/LICENSE)
---
Part of [Charm](https://charm.land).
<a href="https://charm.sh/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
<a href="https://charm.land/"><img alt="The Charm logo" width="400" src="https://stuff.charm.sh/charm-banner-next.jpg" /></a>
<!--prettier-ignore-->
Charm热爱开源 • Charm loves open source