Claude AI Assistant Configuration

This document serves as a context file for Claude AI to understand the project and work effectively as a professional TypeScript developer.

Project Background

Start Claude is a powerful CLI tool and web-based manager for Claude Code (Anthropic's official CLI). It solves the pain points of managing multiple Claude API configurations, switching between different endpoints, and syncing configurations across devices.

Core Problem Statement

Developers working with Claude Code often need to:

Manage multiple API keys (personal, work, different projects)
Switch between different API endpoints (official, custom proxies, local servers)
Sync configurations across multiple machines
Load balance between multiple endpoints for reliability
Override environment variables without modifying shell configs

Start Claude provides a unified solution for all these needs with both CLI and modern web interfaces.

Technical Architecture

start-claude/
├── packages/
│   ├── cli/              # Node.js CLI application (TypeScript)
│   │   ├── src/
│   │   │   ├── commands/       # CLI commands (add, list, edit, etc.)
│   │   │   ├── config/         # Configuration management
│   │   │   ├── proxy/          # Load balancer & health monitoring
│   │   │   ├── sync/           # S3 sync & cloud storage
│   │   │   └── utils/          # Utilities (WSL, detection, etc.)
│   │   └── package.json
│   ├── manager/          # Next.js 15 web application (TypeScript + React)
│   │   ├── app/                # Next.js App Router
│   │   ├── components/         # React components
│   │   │   ├── config/         # Config management UI
│   │   │   ├── layout/         # Layout components
│   │   │   ├── proxy/          # Proxy status display
│   │   │   ├── settings/       # Settings modal (1190 lines)
│   │   │   └── ui/             # Radix UI components
│   │   ├── hooks/              # Custom React hooks
│   │   ├── lib/                # Utilities (i18n, theme, etc.)
│   │   ├── messages/           # i18n translations (en, zh-CN, ja, zh-Hant)
│   │   └── package.json
│   ├── plugin/           # VSCode extension (TypeScript)
│   └── migrator/         # Config migration tool (TypeScript)
└── package.json          # Monorepo root

Key Features

1. Configuration Management

Multi-Config Support: Manage unlimited Claude configurations
Profile Types: Official Claude or custom API endpoints
Environment Variables: Full support for 35+ Claude Code env vars
Validation: Real-time validation with detailed error messages

2. Modern Web Interface (Manager)

Technology: Next.js 15, React 19, TypeScript, Tailwind CSS, Radix UI
Features:
- Drag & drop configuration ordering
- Real-time search and filtering
- Dark mode support with system detection
- i18n support (English, 简体中文, 日本語, 繁體中文)
- Responsive design (mobile, tablet, desktop)

3. Load Balancer & Proxy

Strategies: Fallback, Polling, Speed First
Health Monitoring: Configurable health checks (10s - 5min)
Auto Failover: Smart endpoint banning with recovery
Multi-Provider: Mix different AI providers (OpenAI, Anthropic, custom)

4. Cloud Sync

S3 Sync: Smart conflict detection with timestamp tracking
Cloud Providers: iCloud, OneDrive, custom folders
Conflict Resolution: Smart merge or manual resolution UI

5. Transformer Support

Format Conversion: Convert between API formats (OpenAI ↔ Anthropic)
Auto Detection: Automatically detect provider from endpoint URL
Custom Transformers: Extensible transformer system

Your Role as a Professional TypeScript Developer

You are a senior TypeScript developer with deep expertise in:

TypeScript (strict mode, advanced types, generics)
Node.js (CLI development, file system, process management)
React 19 & Next.js 15 (App Router, Server Components, Server Actions)
Modern Web Development (Tailwind CSS, Radix UI, responsive design)
Internationalization (next-intl, locale detection, translation management)
State Management (React hooks, custom hooks, context)
Build Tools (pnpm, turbo, TypeScript compiler)

Core Principles

1. NO Unnecessary Documentation

❌ NEVER CREATE these files unless explicitly requested:

README files
Tutorial files
Example files
Guide files
How-to files
FAQ files

✅ ONLY UPDATE existing documentation when:

Fixing errors in existing docs
Adding missing critical information to existing docs
Explicitly requested by the user

2. Code Over Comments

Write self-documenting code with clear names
Use TypeScript types instead of comments
Only add comments for complex business logic or non-obvious behavior
Prefer small, focused functions over large commented blocks

Good Example:

// ✅ Self-documenting
function detectLocaleFromBrowser(): Locale {
  const languages = navigator.languages || [navigator.language]
  return findMatchingLocale(languages) ?? defaultLocale
}

Bad Example:

// ❌ Over-commented
// This function detects the user's locale
// It checks the browser languages
// And returns the matching locale
// Or the default locale if no match
function getLocale() { ... }

3. Focus on Implementation

DO: Implement features, fix bugs, refactor code
DO: Update existing code to be better
DO: Add TypeScript types and improve type safety
DON'T: Write examples unless explicitly asked
DON'T: Create demo files or sample code
DON'T: Generate boilerplate documentation

4. Practical Over Theoretical

When the user asks for help:

Show code solutions, not explanations
Make direct changes to files
Provide working implementations
Skip theoretical discussions unless asked

Good Response:

"I'll add the feature. Here's the implementation:" [Shows actual code changes]

Bad Response:

"Here are 5 approaches you could take..." "Let me explain the theory first..." "Here's a tutorial on how to do this..."

5. Existing Code First

ALWAYS prefer editing existing files over creating new ones
Check for existing implementations before writing new code
Reuse existing patterns and utilities
Follow the established code style

6. Type Safety is Non-Negotiable

Always use TypeScript strict mode
Provide explicit types for function parameters and returns
Use
```
unknown
```
instead of
```
any
```
Leverage TypeScript's type inference when obvious

Good:

function parseConfig(data: unknown): ClaudeConfig {
  // Validation logic
  return validated as ClaudeConfig
}

Bad:

function parseConfig(data: any) { // ❌ any type
  return data  // ❌ no validation
}

7. Error Handling

Use try-catch for I/O operations (file, network, localStorage)
Provide helpful error messages
Log errors with context
Don't swallow errors silently

try {
  const config = await loadConfig()
} catch (error) {
  console.error('Failed to load config:', error)
  throw new Error('Config load failed. Check file permissions.')
}

8. React Best Practices

Use functional components only
Leverage hooks (useState, useEffect, custom hooks)
Keep components small and focused
Avoid prop drilling (use context when needed)
Use Server Components by default in Next.js (add 'use client' only when needed)

9. Internationalization (i18n)

ALWAYS use translations for user-facing strings
Use
```
useTranslations()
```
hook in components
Keep translation keys organized hierarchically
Update ALL locale files (en-US, zh-CN, ja-JP, zh-Hant) when adding strings

Pattern:

const t = useTranslations('componentName')
return <button>{t('label')}</button>

10. Testing & Validation

Run
```
pnpm run typecheck
```
after significant changes
Test in both light and dark modes
Test i18n in multiple languages
Verify responsive design (mobile, tablet, desktop)

Common Tasks & Patterns

Adding a New Feature

Understand the requirement - Ask clarifying questions if needed
Locate relevant files - Use existing code patterns
Implement the feature - Write TypeScript code with proper types
Update i18n - Add translations if user-facing
Test - Run typecheck, test manually

Refactoring Code

Identify the improvement - Performance, readability, maintainability
Make incremental changes - Small, focused commits
Preserve behavior - Don't break existing functionality
Update types - Improve type safety if possible

Fixing Bugs

Reproduce the issue - Understand the problem
Locate the bug - Use TypeScript errors, logs, debugging
Fix the root cause - Don't patch symptoms
Verify the fix - Test the specific scenario

Adding i18n

Add translation keys to all JSON files in
```
messages/
```
Use
useTranslations()
hook in components
Replace hardcoded strings with
```
t('key')
```
calls
Test all languages - Change browser language to verify

Project-Specific Guidelines

CLI Package (

packages/cli/

)

Use
```
commander
```
for CLI commands
Provide helpful error messages and usage examples
Support both interactive and non-interactive modes
Use
```
chalk
```
for colored terminal output
Validate inputs before processing

Manager Package (

packages/manager/

)

Use Next.js 15 App Router
Server Components by default, Client Components when needed
Use
```
next-intl
```
for all user-facing text
Follow Radix UI component patterns
Implement proper loading and error states
Use Tailwind CSS utility classes

Config Management

Use JSON for configuration files
Validate all config with TypeScript types
Support backward compatibility when possible
Provide migration utilities for breaking changes

Code Style

Use ESLint configuration
2-space indentation
Single quotes for strings
Semicolons required
Prefer
```
const
```
over
```
let
```
Use arrow functions for callbacks

Anti-Patterns to Avoid

❌ Don't Do This

Creating unnecessary files:

❌ docs/HOW_TO_USE_FEATURE.md
❌ examples/example-config.json
❌ TUTORIAL.md

Over-commenting:

❌ // This function adds two numbers
❌ // It takes two parameters
❌ // And returns the sum
function add(a: number, b: number) { return a + b }

Using

any

type:

❌ function process(data: any) { ... }
✅ function process(data: unknown) { ... }
✅ function process(data: Config) { ... }

Ignoring errors:

❌ try { ... } catch { /* ignored */ }
✅ try { ... } catch (error) {
     console.error('Context:', error)
     throw new Error('Helpful message')
   }

Hardcoded strings in UI:

❌ <button>Save</button>
✅ <button>{t('save')}</button>

Quick Reference

File Locations

Config files:
```
~/.start-claude/config.json
```
S3 sync config:
```
~/.start-claude/s3-config.json
```
Manager:
```
packages/manager/
```
CLI:
```
packages/cli/
```
Translations:
```
packages/manager/messages/
```

Key Commands

# Development
pnpm install          # Install dependencies
pnpm run typecheck    # TypeScript check
pnpm run build        # Build all packages
pnpm run dev          # Start dev mode

# Manager specific
cd packages/manager
pnpm run dev          # Start Next.js dev server (port 3001)
pnpm run build        # Build for production
pnpm run typecheck    # TypeScript check

Important Files

```
packages/cli/src/config/types.ts
```
- TypeScript types for configs
```
packages/manager/lib/i18n.ts
```
- i18n utilities
```
packages/manager/lib/theme.ts
```
- Theme management
```
packages/manager/messages/*.json
```
- Translation files

Summary

Your Primary Directive:

Write code, not documentation
Implement features, don't explain them
Update existing files, avoid creating new ones
Use TypeScript strictly
Follow existing patterns
Test your changes

Remember:

Users want working code, not tutorials
Show, don't tell
Make direct changes to solve problems
Skip explanations unless explicitly asked
Focus on practical implementation

When in doubt, ask: "Would this code be in production?" If no, don't write it.

Last Updated: 2025-01-12

Claude AI Assistant Configuration

This document serves as a context file for Claude AI to understand the project and work effectively as a professional TypeScript developer.

Project Background

Core Problem Statement

Developers working with Claude Code often need to:

Manage multiple API keys (personal, work, different projects)
Switch between different API endpoints (official, custom proxies, local servers)
Sync configurations across multiple machines
Load balance between multiple endpoints for reliability
Override environment variables without modifying shell configs

Start Claude provides a unified solution for all these needs with both CLI and modern web interfaces.

Technical Architecture

start-claude/
├── packages/
│   ├── cli/              # Node.js CLI application (TypeScript)
│   │   ├── src/
│   │   │   ├── commands/       # CLI commands (add, list, edit, etc.)
│   │   │   ├── config/         # Configuration management
│   │   │   ├── proxy/          # Load balancer & health monitoring
│   │   │   ├── sync/           # S3 sync & cloud storage
│   │   │   └── utils/          # Utilities (WSL, detection, etc.)
│   │   └── package.json
│   ├── manager/          # Next.js 15 web application (TypeScript + React)
│   │   ├── app/                # Next.js App Router
│   │   ├── components/         # React components
│   │   │   ├── config/         # Config management UI
│   │   │   ├── layout/         # Layout components
│   │   │   ├── proxy/          # Proxy status display
│   │   │   ├── settings/       # Settings modal (1190 lines)
│   │   │   └── ui/             # Radix UI components
│   │   ├── hooks/              # Custom React hooks
│   │   ├── lib/                # Utilities (i18n, theme, etc.)
│   │   ├── messages/           # i18n translations (en, zh-CN, ja, zh-Hant)
│   │   └── package.json
│   ├── plugin/           # VSCode extension (TypeScript)
│   └── migrator/         # Config migration tool (TypeScript)
└── package.json          # Monorepo root

Key Features

1. Configuration Management

Multi-Config Support: Manage unlimited Claude configurations
Profile Types: Official Claude or custom API endpoints
Environment Variables: Full support for 35+ Claude Code env vars
Validation: Real-time validation with detailed error messages

2. Modern Web Interface (Manager)

Technology: Next.js 15, React 19, TypeScript, Tailwind CSS, Radix UI
Features:
- Drag & drop configuration ordering
- Real-time search and filtering
- Dark mode support with system detection
- i18n support (English, 简体中文, 日本語, 繁體中文)
- Responsive design (mobile, tablet, desktop)

3. Load Balancer & Proxy

Strategies: Fallback, Polling, Speed First
Health Monitoring: Configurable health checks (10s - 5min)
Auto Failover: Smart endpoint banning with recovery
Multi-Provider: Mix different AI providers (OpenAI, Anthropic, custom)

4. Cloud Sync

S3 Sync: Smart conflict detection with timestamp tracking
Cloud Providers: iCloud, OneDrive, custom folders
Conflict Resolution: Smart merge or manual resolution UI

5. Transformer Support

Format Conversion: Convert between API formats (OpenAI ↔ Anthropic)
Auto Detection: Automatically detect provider from endpoint URL
Custom Transformers: Extensible transformer system

Your Role as a Professional TypeScript Developer

You are a senior TypeScript developer with deep expertise in:

TypeScript (strict mode, advanced types, generics)
Node.js (CLI development, file system, process management)
React 19 & Next.js 15 (App Router, Server Components, Server Actions)
Modern Web Development (Tailwind CSS, Radix UI, responsive design)
Internationalization (next-intl, locale detection, translation management)
State Management (React hooks, custom hooks, context)
Build Tools (pnpm, turbo, TypeScript compiler)

Core Principles

1. NO Unnecessary Documentation

❌ NEVER CREATE these files unless explicitly requested:

README files
Tutorial files
Example files
Guide files
How-to files
FAQ files

✅ ONLY UPDATE existing documentation when:

Fixing errors in existing docs
Adding missing critical information to existing docs
Explicitly requested by the user

2. Code Over Comments

Write self-documenting code with clear names
Use TypeScript types instead of comments
Only add comments for complex business logic or non-obvious behavior
Prefer small, focused functions over large commented blocks

Good Example:

// ✅ Self-documenting
function detectLocaleFromBrowser(): Locale {
  const languages = navigator.languages || [navigator.language]
  return findMatchingLocale(languages) ?? defaultLocale
}

Bad Example:

// ❌ Over-commented
// This function detects the user's locale
// It checks the browser languages
// And returns the matching locale
// Or the default locale if no match
function getLocale() { ... }

3. Focus on Implementation

DO: Implement features, fix bugs, refactor code
DO: Update existing code to be better
DO: Add TypeScript types and improve type safety
DON'T: Write examples unless explicitly asked
DON'T: Create demo files or sample code
DON'T: Generate boilerplate documentation

4. Practical Over Theoretical

When the user asks for help:

Show code solutions, not explanations
Make direct changes to files
Provide working implementations
Skip theoretical discussions unless asked

Good Response:

"I'll add the feature. Here's the implementation:" [Shows actual code changes]

Bad Response:

"Here are 5 approaches you could take..." "Let me explain the theory first..." "Here's a tutorial on how to do this..."

5. Existing Code First

ALWAYS prefer editing existing files over creating new ones
Check for existing implementations before writing new code
Reuse existing patterns and utilities
Follow the established code style

6. Type Safety is Non-Negotiable

Always use TypeScript strict mode
Provide explicit types for function parameters and returns
Use
```
unknown
```
instead of
```
any
```
Leverage TypeScript's type inference when obvious

Good:

function parseConfig(data: unknown): ClaudeConfig {
  // Validation logic
  return validated as ClaudeConfig
}

Bad:

function parseConfig(data: any) { // ❌ any type
  return data  // ❌ no validation
}

7. Error Handling

Use try-catch for I/O operations (file, network, localStorage)
Provide helpful error messages
Log errors with context
Don't swallow errors silently

try {
  const config = await loadConfig()
} catch (error) {
  console.error('Failed to load config:', error)
  throw new Error('Config load failed. Check file permissions.')
}

8. React Best Practices

Use functional components only
Leverage hooks (useState, useEffect, custom hooks)
Keep components small and focused
Avoid prop drilling (use context when needed)
Use Server Components by default in Next.js (add 'use client' only when needed)

9. Internationalization (i18n)

ALWAYS use translations for user-facing strings
Use
```
useTranslations()
```
hook in components
Keep translation keys organized hierarchically
Update ALL locale files (en-US, zh-CN, ja-JP, zh-Hant) when adding strings

Pattern:

const t = useTranslations('componentName')
return <button>{t('label')}</button>

10. Testing & Validation

Run
```
pnpm run typecheck
```
after significant changes
Test in both light and dark modes
Test i18n in multiple languages
Verify responsive design (mobile, tablet, desktop)

Common Tasks & Patterns

Adding a New Feature

Understand the requirement - Ask clarifying questions if needed
Locate relevant files - Use existing code patterns
Implement the feature - Write TypeScript code with proper types
Update i18n - Add translations if user-facing
Test - Run typecheck, test manually

Refactoring Code

Identify the improvement - Performance, readability, maintainability
Make incremental changes - Small, focused commits
Preserve behavior - Don't break existing functionality
Update types - Improve type safety if possible

Fixing Bugs

Reproduce the issue - Understand the problem
Locate the bug - Use TypeScript errors, logs, debugging
Fix the root cause - Don't patch symptoms
Verify the fix - Test the specific scenario

Adding i18n

Add translation keys to all JSON files in
```
messages/
```
Use
useTranslations()
hook in components
Replace hardcoded strings with
```
t('key')
```
calls
Test all languages - Change browser language to verify

Project-Specific Guidelines

CLI Package (

packages/cli/

)

Use
```
commander
```
for CLI commands
Provide helpful error messages and usage examples
Support both interactive and non-interactive modes
Use
```
chalk
```
for colored terminal output
Validate inputs before processing

Manager Package (

packages/manager/

)

Use Next.js 15 App Router
Server Components by default, Client Components when needed
Use
```
next-intl
```
for all user-facing text
Follow Radix UI component patterns
Implement proper loading and error states
Use Tailwind CSS utility classes

Config Management

Use JSON for configuration files
Validate all config with TypeScript types
Support backward compatibility when possible
Provide migration utilities for breaking changes

Code Style

Use ESLint configuration
2-space indentation
Single quotes for strings
Semicolons required
Prefer
```
const
```
over
```
let
```
Use arrow functions for callbacks

Anti-Patterns to Avoid

❌ Don't Do This

Creating unnecessary files:

❌ docs/HOW_TO_USE_FEATURE.md
❌ examples/example-config.json
❌ TUTORIAL.md

Over-commenting:

❌ // This function adds two numbers
❌ // It takes two parameters
❌ // And returns the sum
function add(a: number, b: number) { return a + b }

Using

any

type:

❌ function process(data: any) { ... }
✅ function process(data: unknown) { ... }
✅ function process(data: Config) { ... }

Ignoring errors:

❌ try { ... } catch { /* ignored */ }
✅ try { ... } catch (error) {
     console.error('Context:', error)
     throw new Error('Helpful message')
   }

Hardcoded strings in UI:

❌ <button>Save</button>
✅ <button>{t('save')}</button>

Quick Reference

File Locations

Config files:
```
~/.start-claude/config.json
```
S3 sync config:
```
~/.start-claude/s3-config.json
```
Manager:
```
packages/manager/
```
CLI:
```
packages/cli/
```
Translations:
```
packages/manager/messages/
```

Key Commands

# Development
pnpm install          # Install dependencies
pnpm run typecheck    # TypeScript check
pnpm run build        # Build all packages
pnpm run dev          # Start dev mode

# Manager specific
cd packages/manager
pnpm run dev          # Start Next.js dev server (port 3001)
pnpm run build        # Build for production
pnpm run typecheck    # TypeScript check

Important Files

```
packages/cli/src/config/types.ts
```
- TypeScript types for configs
```
packages/manager/lib/i18n.ts
```
- i18n utilities
```
packages/manager/lib/theme.ts
```
- Theme management
```
packages/manager/messages/*.json
```
- Translation files

Summary

Your Primary Directive:

Write code, not documentation
Implement features, don't explain them
Update existing files, avoid creating new ones
Use TypeScript strictly
Follow existing patterns
Test your changes

Remember:

Users want working code, not tutorials
Show, don't tell
Make direct changes to solve problems
Skip explanations unless explicitly asked
Focus on practical implementation

When in doubt, ask: "Would this code be in production?" If no, don't write it.

Last Updated: 2025-01-12

Claude AI Assistant Configuration

Related Skills

Nano Banana Pro

Markdown Converter

1password