Crush — API Surface#

API types#

Crush exposes two distinct API surfaces: a CLI and an optional REST/HTTP API. There is no gRPC, no public library API, and no formal plugin interface — though MCP (Model Context Protocol) integration acts as a runtime extension mechanism.

CLI#

Framework#

Cobra (github.com/spf13/cobra) wrapped with charm.land/fang/v2 (Charmbracelet’s Cobra wrapper that adds Ctrl-C handling and colorprofile-aware output).

Command structure#

crush                           Interactive TUI mode (default command)
crush run [prompt...]           Non-interactive single-prompt execution
crush session                   Session management (alias: sessions, s)
  session list                  List all sessions (alias: ls)
  session show <id>             Show session details with message history
  session last                  Show most recent session
  session delete <id>           Delete a session
  session rename <id> <title>   Rename a session
crush server                    Start the background server daemon
crush login [platform]          Authenticate with a provider (alias: auth)
crush models [filter]           List available models from configured providers
crush stats                     Show usage statistics (opens HTML report)
crush projects                  List tracked project directories
crush dirs                      Print config/data directory paths
  dirs config                   Print only config directory
  dirs data                     Print only data directory
crush logs                      View crush log output (--follow for tail)
crush update-providers [path]   Update Catwalk / Hyper provider data
crush schema                    Generate JSON schema for config (hidden)

Flag patterns#

Global (persistent) flags — available on all subcommands:

Root command (TUI) flags:

run subcommand flags:

session list/show/last/delete/rename flags: All session subcommands support --json for machine-readable output — explicitly designed for agent-to-agent use.

Notable design choices#

• crush run accepts stdin piping (cat file | crush run "analyze this") — first-class scripting surface
• --session/--continue are declared mutually exclusive via cobra.MarkFlagsMutuallyExclusive
• --yolo is a root-level flag only (not on run), limiting the blast radius of auto-permission to intentional invocations
• crush session subcommands include --json output mode for machine-readable results, anticipating agent-as-caller use cases

REST/HTTP API (client/server mode)#

Overview#

The REST API is used internally when CRUSH_CLIENT_SERVER=1 is set. The server daemon is auto-started by the client binary (see architecture result). The API is also the foundation for future IDE integrations (VS Code extension, etc.) and multi-client access.

• Transport: stdlib net/http over a Unix socket (/tmp/crush-<uid>.sock) on Linux/macOS or a Windows named pipe. TCP is also supported (tcp://host:port).
• Protocol: HTTP/1.1 and unencrypted HTTP/2 (both enabled via http.Protocols)
• Router: stdlib http.ServeMux with Go 1.22+ pattern syntax (e.g., GET /v1/health, DELETE /v1/workspaces/{id})
• Versioning: All routes are under /v1/
• Documentation: Swagger UI served at /v1/docs/ via swaggo/http-swagger
• Authentication: None — the Unix socket provides OS-level access control (only the owning user can connect); TCP mode relies on network-level controls

Middleware chain#

A single middleware is applied globally:

loggingHandler → http.ServeMux (route dispatch)

loggingHandler is a minimal inline implementation (no third-party middleware library) that logs method, path, remote addr, user agent, status code, and duration via slog.

Route catalog#

System endpoints#

Workspace management#

Session management#

Agent control#

Events (SSE streaming)#

The events stream carries typed payloads via pubsub.Payload envelope with a PayloadType discriminator. Event types published:

• LSPEvent — LSP server state changes, diagnostic counts
• MCPEvent — MCP connection state, tool/prompt/resource list changes
• PermissionRequest — agent requests permission before a tool call
• PermissionNotification — permission granted/denied result
• Message — new or updated LLM message (streaming-friendly)
• Session — session created/updated
• File — file history entry (edit tracked)
• AgentEvent — agent lifecycle notifications (started, finished, error)

Permissions#

File tracking#

Configuration management#

LSP management#

Workspace configuration#

Project initialization#

MCP management#

MCP — Extension / Plugin Mechanism#

While crush has no formal plugin system, MCP (Model Context Protocol) serves as the runtime extension point for adding tools, prompts, and resources to the agent.

• Mechanism: JSON-RPC over stdio or HTTP, following the MCP specification. Crush connects to externally configured MCP servers at startup.
• Extension points: External MCP servers can register additional tools (callable by the LLM), prompts (reusable instruction templates), and resources (file-like content the LLM can read).
• Configuration: MCP servers are listed in crush.json under the mcp section with command + args or HTTP URL.
• First-class support: The REST API exposes MCP management routes (/mcp/states, /mcp/refresh-*, /mcp/docker/*) and the TUI has MCP state display.
• Docker integration: A dedicated Docker MCP server can be enabled/disabled via the API, suggesting first-party container tooling integration.

Library API#

Crush is not designed as a library. All packages reside under internal/ — the only public entry point is main.go. There are no exported packages for third-party import.

The Workspace interface (internal/workspace) is the natural seam for IDE integration, but it is explicitly internal. Future IDE clients would consume the REST API over the Unix socket rather than importing the Go package directly.

Notable API design observations#

1. REST API mirrors the Workspace interface 1:1. Every method on the Workspace interface has a corresponding HTTP endpoint. The REST API is a faithful HTTP translation of the in-process Go interface — generated manually but mechanically consistent. This makes the client-server mode a thin HTTP wrapper rather than a separate design.

2. SSE over HTTP/2 for real-time events. The GET /v1/workspaces/{id}/events endpoint is a Server-Sent Events stream. Using unencrypted HTTP/2 on Unix sockets means the single connection can multiplex SSE alongside REST calls without separate WebSocket infrastructure.

3. No authentication. Security relies on Unix socket file permissions. This is idiomatic for local daemon patterns (Docker, containerd, systemd socket activation) but means TCP mode is explicitly for “advanced users” and not production-hardened.

4. Swagger docs auto-generated. All handler functions carry @Summary, @Tags, and @Router annotations, and the OpenAPI spec is embedded via github.com/swaggo/http-swagger. This suggests the REST API is intended as a stable, documented interface for future tooling.

5. --json flag pattern for agent-as-caller. The session subcommands all support --json output — an explicit acknowledgment that CLI commands will be called by other agents or automation scripts, not just humans.