Claude Code Mux's design philosophy is "Simplify complex AI routing".
Our goal is to minimize the complexity developers face when using multiple AI providers, making every aspect of configuration, monitoring, and management intuitive.
- Hide complex AI routing logic from users, exposing only essential configurations.
- Aim for "minimum steps to desired outcome" in both CLI and Admin UI.
- Keep technical complexity internal, user experience simple.
- Use terminology and structures familiar to developers.
- Share the same mental model between config files (TOML) and UI.
- Error messages clearly communicate "what went wrong" and "how to fix it".
- ~5MB memory, <1ms routing overhead is not just performance metrics—it's user experience.
- Fast responses build trust, lightweight resource usage simplifies deployment.
Show users the value of configuration first, expose complex settings later.
- ❌ Bad: Immediately require API key, Base URL, and type on one screen when adding a Provider
- ✅ Good: Step-by-step progression: "Which Provider?" → Select type → Name it → Enter API key
- When adding a new feature, can users understand "why they need to do this" first?
- Can complex options be collapsed under "Advanced settings"?
- Are required vs optional fields clearly distinguished?
Users should instantly understand what to select and what to input on each screen.
- ❌ Bad: Abstract labels like "Model mappings configuration"
- ✅ Good: "Select Provider" → "Actual model name" → "Choose which Provider to use for claude-sonnet-4"
- Does each input field have placeholder or helper text?
- Are choices (radio, select) limited to 3-5 options?
- Do error messages explain "what's wrong and how to fix it"?
Each screen handles only one purpose.
- ✅ Overview page: View overall status only
- ✅ Provider management page: View, add, edit, delete Providers only
- ✅ Model management page: View, add, edit, delete Models only
- ✅ Router settings page: Configure routing rules only
- Can you describe this page's core purpose in one sentence?
- Does the page title (h1) accurately reflect user intent?
- Do multiple features on the page not compete with each other?
- ❌ "We are showing you a list of currently configured Providers"
- ✅ "Provider list"
- ✅ "Provider" - Familiar term to developers
- ✅ "Model mapping" - Clear meaning
- ❌ "Inference endpoint configuration" - Unnecessarily complex
- ✅ "Add Provider"
- ✅ "Edit Model"
- ❌ "Add" (unclear what's being added)
- Display routing overhead and memory usage in Admin UI in real-time
- Users can immediately see "how efficient my configuration is"
- Track error rate and response time per Provider
- Immediately identify and respond to problematic Providers
- Are important metrics displayed numerically?
- Can problem situations be immediately noticed via red/warning icons?
- Can statistics be viewed by time period and Provider?
- All features must be accessible via keyboard only
- Tab order must be logical
- Focus state must be clearly visible
- Buttons are
<button>, links are<a>, forms are<form> - Screen readers must understand page structure
- Can all tasks be completed with just Tab + Enter, without a mouse?
- Is information not conveyed by color alone? (colorblind support)
- Are error messages readable by screen readers?
- Button click → Immediately show loading state
- Form submit → Immediately show success/failure notification
- Config change → Show "unsaved changes" indicator
- Show basic settings first, expose rest via "Advanced settings" button
- Provider addition progresses step-by-step with ability to go back
- Is there immediate feedback for every action?
- Are users not left waiting during loading?
- Is Undo/cancel provided for destructive actions?
- Validate TOML config file before saving
- Invalid config won't save and provides clear error message
- Provide reasonable defaults when adding new Provider
- Auto-assign Model mapping priorities as 1, 2, 3...
- Test config changes without server restart via hot reload
- One-click "Save & Restart" from Admin UI after config changes
- Is this feature designed with one page/one purpose?
- Does it show value to users first?
- Are questions and choices clear?
- Have you removed meaningless words from all text?
- Is it usable with keyboard only?
- Are error and loading states clear?
- Are required fields clearly marked?
- Does each field have placeholder/helper text?
- Do validation checks (duplicate, format) happen immediately?
- Does the error message explain "what" went wrong?
- Does the error message explain "how" to fix it?
- Is the error visible to users?
- Does the page load in under 2 seconds?
- Does it respond immediately to user actions?
- Have unnecessary network requests been eliminated?
Add Provider
- Name: [ ]
- Type: [Select▼]
- API Key: [ ]
- Base URL: [ ]
- Model list: [ ]
- Enabled: [v]
[Add]
Step 1: Which Provider would you like to add?
○ Anthropic ○ OpenAI ○ OpenRouter
(Large card format for selection)
Step 2: Name your Provider
Name: [anthropic-main]
(This name will be used to reference it in Model mappings)
Step 3: Enter your API key
API Key: [sk-ant-...]
(You can get this from the provider's website)
Step 4: Done!
✓ anthropic-main Provider has been added
Now go to the Model tab to add models using this Provider
- Simplicity Behind
- Simplicity 24
- Toss Tech Blog
- Value First, Cost Later
- Insurance Claim Process
- Design Motivation
- 8 Writing Principles of Toss
- URL-based State Management - Our navigation pattern
- LocalStorage-based State Management - Our state management pattern