Crush

Crush is an agentic AI coding assistant built for developers who live in the terminal. It runs a local server over Unix sockets (or Windows named pipes) that a BubbleTea-based TUI connects to, giving you a responsive, native-feeling interface without ever touching a browser. The server manages independent sessions backed by SQLite, orchestrates named agents (a coder agent and a task agent), integrates Language Server Protocol for real-time code intelligence, and exposes a REST API for programmatic access to workspaces, sessions, and agents.

Crush is provider-agnostic by design. Its Fantasy abstraction layer normalises OpenAI-compatible and Anthropic-compatible APIs so you can point it at any hosted or self-hosted model — GPT-5.4, Claude 4, Gemini, Groq, Llama via OpenRouter, Amazon Bedrock, Azure OpenAI, Vercel AI Gateway, or a local Ollama endpoint — and switch mid-session without losing context. The Catwalk community registry keeps the model list current without requiring a Crush update.

Extensibility is a first-class concern. The Model Context Protocol client supports stdio, http, and sse transports, and full shell-style variable expansion (including $(command)) makes secret management ergonomic on every OS. A hook engine fires user-defined shell commands on events like pre-tool-use — compatible with the Claude Code hook format. A markdown-based skills system lets teams ship reusable agent behaviours (including the built-in crush-config skill that can configure Crush itself via natural language).

Available through Homebrew, NPM, Winget, Scoop, Arch AUR, Nix NUR, Debian/Ubuntu apt, Fedora/RHEL yum, and FreeBSD pkg. Cross-compiled Go binaries ship via Goreleaser for every platform with zero CGO dependencies.

What You Get

• Client-Server Architecture - Crush launches a background JSON-over-HTTP server on a Unix socket (Linux/macOS) or Windows named pipe, and the BubbleTea TUI connects as a lightweight client, keeping the AI engine running even if the terminal is closed.
• Multi-Provider Fantasy Layer - Switch between OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Azure OpenAI, Groq, OpenRouter, Vercel AI Gateway, Hugging Face, io.net, Cerebras, MiniMax, and any OpenAI- or Anthropic-compatible endpoint without leaving the session.
• Catwalk Model Registry - A community-maintained open-source catalogue of Crush-compatible models automatically kept in sync, so new model releases appear in Crush without requiring a version update.
• LSP-Driven Context - Connect any Language Server Protocol server (gopls, typescript-language-server, rust-analyzer, nil for Nix, and more) so the AI receives the same type, symbol, and diagnostic information your editor sees.
• MCP Client with Shell Expansion - Load Model Context Protocol servers over stdio, http, or sse transports; all command, args, env, headers, and url fields support full bash-style variable expansion including $(cat /path/to/token), making secret management first-class on every OS including Windows.
• Hook Engine - Define shell commands that fire on hook events (pre-tool-use, post-session, etc.) in crush.json; the hook format is compatible with Claude Code, so existing hook scripts work without modification.
• Skills System - Ship reusable agent behaviours as markdown files; the built-in crush-config and crush-hooks skills let the AI configure or extend itself, and teams can add custom skills to the project-level or global config directory.
• REST API - Crush exposes a Swagger-documented HTTP API over the local socket for workspaces, sessions, agents, LSP, MCP, and more, enabling scripting, CI integrations, and third-party tooling.

Common Use Cases

• Refactoring with type awareness - A Go developer connects gopls and asks Crush to rename an interface and update all implementations; the LSP context ensures the AI sees actual type signatures rather than guessing from file content alone.
• Internal tool automation - A platform engineer adds a company-internal MCP server exposing deployment APIs, then asks Crush to draft a rollout script that calls those APIs, with the ${DEPLOY_TOKEN:?set DEPLOY_TOKEN} pattern ensuring the secret is required at load time.
• Multi-session parallel work - A developer keeps separate Crush sessions for a backend feature branch and a frontend bug fix, switching between them without losing conversation history since sessions are persisted in SQLite.
• CI-driven code review - A team integrates the Crush REST API into their CI pipeline to run an automated session that checks a PR diff for common errors and posts a summary comment, using a headless session without the TUI.
• Customising AI behaviour with hooks - A security-conscious team adds a pre-tool-use hook that logs all bash tool calls to an audit file, reusing the same hook script they already have for Claude Code.
• Nix infrastructure management - A DevOps engineer connects the nil LSP server and asks Crush to update NixOS module options, with Catwalk providing the latest Gemini Flash model for low-latency edits.

Under The Hood

Architecture Crush follows a clean client-server split: the CLI boots a JSON-over-HTTP server bound to a Unix domain socket (or Windows named pipe), and the BubbleTea v2 TUI operates as a thin client against that server. The internal/app package handles top-level wiring — database, configuration, agent coordinator, LSP manager, MCP clients, and pub-sub event bus — then hands off to the Cobra command tree in internal/cmd. An agent coordinator manages two named agents (coder and task), each backed by an independent session stored in SQLite. The hook engine runs user shell commands in parallel with timeouts and deduplication before and after tool calls. This architecture means the AI loop survives terminal disconnects, and the documented REST API (Swagger at /swagger) gives programmatic access to every internal subsystem.

Tech Stack The project is written in Go 1.26 with CGO disabled and the experimental green-tea GC enabled for reduced pause times. The TUI is built on BubbleTea v2 and Lipgloss v2 from the Charm ecosystem. LLM access goes through Fantasy, a Charm-developed abstraction layer with named providers for Anthropic, OpenAI, Google Gemini, Amazon Bedrock, OpenRouter, Vercel AI Gateway, and more. The Catwalk library ships an embedded, community-maintained model catalogue. SQLite is accessed via sqlc-generated type-safe query functions with go-modernc (pure Go) and ncruces (WASM) build tags for zero-CGO portability. Build and task automation uses Taskfile, and cross-platform binary distribution is handled by Goreleaser with sigstore attestation via cosign.

Code Quality The repository contains an extensive test suite across unit, integration, and end-to-end layers with testify for assertions. Charm’s VCR library records and replays external HTTP interactions for deterministic provider tests; goleak catches goroutine leaks; and synctest enables reproducible concurrency testing. Linting runs golangci-lint with specialised checkers for SQL correctness, context propagation, and log message capitalisation — the last enforced by a custom script in CI. Semantic commits are required by convention, all SQL is managed through sqlc ensuring compile-time correctness, and atomic file writes are used throughout to prevent partial-write corruption.

What Makes It Unique Crush’s most distinctive technical choices are its local client-server topology over Unix sockets (giving it a persistent AI process model that most terminal AI tools lack) and the Fantasy provider abstraction that makes every OpenAI- or Anthropic-compatible API a first-class citizen with zero code changes. The shell-expansion engine embedded in the MCP client brings full bash semantics — including command substitution and required-variable assertions — to secret and credential management on every platform including Windows. The hook system’s compatibility with the Claude Code format is a deliberate design choice that lets organisations share hook scripts across both tools, and the markdown-based skills system allows distributing reusable agent behaviours as plain text files alongside project code.

Self-Hosting

Crush is released under the Functional Source License 1.1 with MIT Future License (FSL-1.1-MIT). This is a source-available licence that permits internal use, non-commercial education, non-commercial research, and professional services work for the full lifetime of the software, but prohibits building a competing commercial product or service on top of it without Charmbracelet’s permission. Crucially, the licence contains an irrevocable grant: two years after each version is published, that version automatically converts to the MIT licence with no restrictions whatsoever. For most self-hosters — individuals and companies running Crush internally as a developer productivity tool — FSL-1.1-MIT is effectively permissive today. The restriction only bites if you intend to redistribute or sell Crush as a product.

Running Crush yourself is operationally lightweight. It is a single statically-linked Go binary with no CGO dependencies, distributed for Linux (amd64/arm64), macOS, Windows, FreeBSD, OpenBSD, and NetBSD. State lives in two JSON files (global config and ephemeral data) and a SQLite database, all under $HOME/.config/crush and $HOME/.local/share/crush by default. These paths are overridable via environment variables, which makes containerising or restricting the data location straightforward. There is no bundled web server, no container daemon, and no required external services — the only runtime dependencies are the LLM provider API keys you configure. You are responsible for key rotation, API cost monitoring, and keeping the binary updated, but the release cadence (multiple releases per week in 2026) means security and feature patches are available quickly.

Charmbracelet does not currently offer a managed cloud tier for Crush itself, but the HYPER_API_KEY environment variable points to Charm Hyper, a subscription AI gateway they operate that provides a curated selection of models. Using Hyper trades provider flexibility for a single managed billing relationship and removes the need to manage individual API keys for every provider. Without a managed tier there are no SLAs, no managed upgrades, no built-in audit logging beyond your own hook scripts, and no support beyond the public Discord, Slack, and GitHub issues. Teams with strict uptime or compliance requirements should factor in the operational overhead of self-managing the binary, the SQLite data store, and the API credentials across developer machines or shared CI environments.