# Common Change Patterns

Recipes for the most frequent types of changes in aimux.

## Add a New Provider

1. Create `internal/provider/yourprovider.go` implementing all `Provider` interface methods
2. Add compile-time check: `var _ Provider = (*YourProvider)(nil)`
3. Register in `tui/app.go` `NewApp()` providers list
4. Add default config in `config/config.go` `Default()`
5. Add model pricing in `cost/tracker.go`
6. Add tests in `internal/provider/yourprovider_test.go`

Example: see `internal/provider/claude.go` for a complete implementation.

## Add a New TUI View

1. Create `internal/tui/views/yourview.go` with a Bubble Tea `Model` struct
2. Implement `Init()`, `Update()`, `View()` methods
3. Add navigation key in `tui/app.go` `Update()` switch
4. Add hint bar entry in `tui/app.go` `updateHints()`
5. Add tests (view logic should be in core packages, not in the view itself)

## Add a New API Endpoint (Web UI)

1. Add handler in `internal/frontend/web/` using core packages for logic
2. Register route in the HTTP mux setup
3. Add corresponding React component in `web/src/`
4. Never reimplement Go logic in TypeScript; fetch from the API instead

## Add a New Keybinding

1. Add key handler in the relevant view's `Update()` method
2. Update the hint bar in `tui/app.go` `updateHints()`
3. Document in `docs-site/src/content/docs/` if user-facing

## Fix a Bug Across All Providers

1. Check if the bug exists in all three providers (Claude, Codex, Gemini)
2. Fix in shared helpers (`provider/helpers.go`) if possible
3. If provider-specific, fix in each provider file
4. Run `go test ./internal/provider/... -timeout 30s` to verify all three
