Skip to main content
This guide will walk you through your first Crush session, from installation to your first AI-assisted code changes.

​
Before you begin

You’ll need an API key from at least one LLM provider. Crush supports many providers, including: For this quickstart, we recommend starting with Anthropic or OpenAI.

​
Get started in four steps

1

Install Crush

Install Crush using your preferred package manager:
brew install charmbracelet/tap/crush
See the installation guide for all installation methods including Windows, Arch Linux, Nix, and more.
2

Set up your API key

Configure your API key using an environment variable. The quickest way is to export it in your shell:
export ANTHROPIC_API_KEY=your-key-here
If you don’t set an API key, Crush will prompt you to enter one when you first launch it. You can also configure providers via the crush.json configuration file.

​
Supported environment variables

Crush recognizes API keys for many providers:
Environment VariableProvider
ANTHROPIC_API_KEYAnthropic (Claude)
OPENAI_API_KEYOpenAI (GPT)
GEMINI_API_KEYGoogle Gemini
GROQ_API_KEYGroq
OPENROUTER_API_KEYOpenRouter
VERCEL_API_KEYVercel AI Gateway
HF_TOKENHugging Face Inference
CEREBRAS_API_KEYCerebras
See the providers configuration guide for the complete list and advanced setup options.
3

Launch Crush

Navigate to your project directory and start Crush:
cd /path/to/your/project
crush
Running Crush from your project directory allows it to understand your codebase structure, read configuration files, and use LSPs for code intelligence.
When Crush starts, you’ll see:
  • The Crush welcome screen with the logo
  • A model selector if you have multiple providers configured
  • A prompt where you can type your request
The terminal interface includes:
  • Message area: Conversation history with syntax-highlighted code
  • Input prompt: Where you type your requests
  • Status bar: Shows current model, session name, and token usage
4

Your first interaction

Try asking Crush to help you with a coding task. Here are some example prompts to get started:
What does this project do? Give me an overview of the codebase structure.
Crush will analyze your files and provide a summary of your project architecture.
Create a new function in utils.go that parses command-line flags and returns a config struct.
Crush will:
  1. Read relevant files to understand your project structure
  2. Generate the code following your project’s patterns
  3. Ask permission before writing files
  4. Create or edit the necessary files
I'm getting a null pointer error when running the server. Can you help me find and fix it?
Crush will:
  1. Search for potential null pointer issues
  2. Use LSP diagnostics if available
  3. Suggest fixes with explanations
  4. Apply the fixes with your permission
Refactor the authentication logic in auth.go to use the new JWT library.
Crush will analyze your existing code and refactor it while maintaining functionality.

​
Tool permissions

When Crush wants to execute tools (like editing files or running commands), it will ask for your permission:
Crush wants to use the edit tool:
• Edit src/utils.go

[a]llow  [d]eny  [v]iew  allow [A]ll
  • Press a to allow this specific action
  • Press A to allow all tools for this session
  • Press v to view the changes before deciding
  • Press d to deny the action
You can skip permission prompts entirely with the --yolo flag, but use this with extreme caution as it allows Crush to make changes without confirmation.

​
Essential keyboard shortcuts

While chatting with Crush:
  • Ctrl+C: Cancel current operation or exit
  • Ctrl+D: Send message (alternative to Enter)
  • Up/Down arrows: Navigate message history
  • Ctrl+L: Clear screen
  • Ctrl+R: Restart LSP servers

​
Working with sessions

Crush maintains conversation context in sessions. Each session is tied to your current directory.

​
Create a new session

crush --session my-feature

​
List all sessions

crush sessions

​
Resume a session

Just navigate to the same directory and run crush with the same session name. Crush remembers your conversation history and project context.
Use different sessions for different features or experiments. This keeps your context focused and makes it easier to track changes.

​
Switching models mid-session

One of Crush’s unique features is the ability to switch LLM providers without losing context:
  1. Press Ctrl+M (or type /models) during a session
  2. Select a different model from the list
  3. Continue your conversation with the new model
This is useful for:
  • Comparing model outputs on the same task
  • Using faster models for simple tasks, more powerful ones for complex problems
  • Managing costs by switching to cheaper models when appropriate

​
Configuration basics

Crush looks for configuration in these locations (in order of priority):
  1. .crush.json (hidden, in current directory)
  2. crush.json (in current directory)
  3. ~/.config/crush/crush.json (global configuration)
Here’s a minimal configuration example:
crush.json
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "context_paths": ["AGENTS.md", "docs/"],
    "debug": false
  },
  "permissions": {
    "allowed_tools": ["view", "ls", "grep"]
  }
}
This configuration:
  • Adds AGENTS.md and the docs/ directory to the context
  • Pre-allows view, ls, and grep tools without prompting
See the configuration overview for comprehensive documentation.

​
Next steps

Now that you’ve completed your first Crush session, explore these topics:

Configure Providers

Set up multiple LLM providers and customize model settings

LSP Integration

Enable Language Server Protocol support for better code intelligence

Context Files

Learn how to provide project-specific instructions to Crush

MCP Servers

Extend Crush capabilities with Model Context Protocol servers
Need help? Join the Crush community on Discord, Slack, or ask questions on GitHub Discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us