How charmbracelet/catwalk works
Project type and purpose
• This is an open-source Go application and library called “Catwalk.”
• Purpose: maintain a database of CRUSH-compatible ML model providers.
• It ships as:
• A CLI binary (cmd/openrouter & root main.go)
• A Go client package (pkg/catwalk) for embedding in other tools
File structure
• cmd/openrouter
– CLI entrypoint: parses commands, flags, user input
• main.go (root)
– Initializes the Catwalk service (root command, global flags)
• pkg/catwalk
– client.go: primary Client type to query providers
– provider.go: Provider interface
– pkg.go: package-level constructors
• internal/providers
– providers.go: registry loader
– configs/*.json: metadata for each external provider
• go.mod/go.sum + .github/workflows + goreleaser configs
– Go module definition, CI/CD build & release pipelines
README for additional insights
• “A database for Crush-compatible models.”
a. Main components
1. CLI Application
• cmd/openrouter
• root main.go
2. Catwalk Client Library
• pkg/catwalk
3. Provider Layer
• internal/providers
• JSON config store
4. External Model Provider APIs
• OpenAI, Anthropic, VertexAI, etc.
• GitHub Actions
• GoReleaser
b. Relationships & interactions
• CLI → invokes → Catwalk Client Library
• Client Library → loads JSON configs → instantiates Providers
• Providers → perform HTTP calls → External APIs
• API responses → mapped to uniform Model metadata → returned up call chain → displayed by CLI
• Push code → CI workflows → build/test → GoReleaser → published binaries
c. Architectural patterns & design principles
• Layered architecture: Presentation (CLI), Domain (client package), Infrastructure (providers + configs), External Services
• Interface-based extensibility: Provider interface + pluggable JSON configs
• Configuration-driven behavior: metadata stored in versioned JSON files
• Single binary distribution with embedded assets
d. Key technologies
• Go (modules, standard library HTTP client)
• JSON (provider metadata)
• GitHub Actions (CI), GoReleaser (CD)