Configuration Store

Relevant source files

The following files were used as context for generating this wiki page:

• src/electron/libs/config-store.ts
• src/electron/libs/claude-settings.ts
• src/electron/main.ts
• src/ui/components/SettingsModal.tsx
• types.d.ts
• src/electron/libs/util.ts

The Configuration Store is a critical subsystem responsible for managing API credentials and environment settings required to interface with Anthropic's Claude models. It provides a persistent storage mechanism for API keys, base URLs, and model identifiers, ensuring that the application can maintain a consistent connection to the AI backend across sessions.

This module acts as a bridge between the user interface, the local filesystem, and the underlying Claude Agent SDK. It supports two primary modes of configuration: a dedicated application-specific storage (api-config.json) and a fallback mechanism that inherits settings from the official Claude Code CLI configuration (~/.claude/settings.json).

Sources: src/electron/libs/config-store.ts, src/electron/libs/claude-settings.ts:25-50, README.md:19-25

Core Data Structures

The system relies on a standardized ApiConfig type to ensure consistency when passing configuration data between the Electron main process and the React frontend.

Field	Type	Description
apiKey	string	The authentication token for the API.
baseURL	string	The endpoint URL for API requests.
model	string	The specific model identifier (e.g., claude-3-5-sonnet-20241022).
apiType	ApiType	Identifier for the provider, defaults to "anthropic".

Sources: src/electron/libs/config-store.ts:6-11, types.d.ts:16-18

Persistent Storage Mechanism

The Configuration Store utilizes the Electron userData path to store application-specific settings in a JSON file named api-config.json.

File Operations

The store provides high-level functions to manage the lifecycle of the configuration file:

• loadApiConfig(): Reads and validates the JSON file. It ensures required fields (apiKey, baseURL, model) are present and assigns a default apiType if missing.
• saveApiConfig(config): Ensures the userData directory exists, validates the input config, and writes it to disk with pretty-printing.
• deleteApiConfig(): Removes the configuration file from the filesystem.

Sources: src/electron/libs/config-store.ts:13-72

The diagram above illustrates the flow of saving a configuration from the UI to the local filesystem.
Sources: src/electron/libs/config-store.ts:46-65, src/electron/main.ts:121-131

Configuration Retrieval Logic

The system employs a priority-based retrieval strategy. When the application requires API credentials (e.g., for session initialization or title generation), it invokes getCurrentApiConfig().

1. UI/Local Config: It first attempts to load settings from the application's local api-config.json.
2. External Fallback: If no local config is found, it attempts to read ~/.claude/settings.json created by the Claude Code CLI.
3. Persistence: If it successfully falls back to the CLI settings, it automatically persists those settings into the local api-config.json for future use.

Sources: src/electron/libs/claude-settings.ts:25-63

This sequence shows how the system prioritizes local storage while remaining compatible with external CLI tools.
Sources: src/electron/libs/claude-settings.ts:25-72

Integration with AI Services

The Configuration Store is not just a passive data holder; it actively prepares the execution environment for the Claude Agent SDK.

Environment Variable Mapping

The function buildEnvForConfig maps the ApiConfig object to the environment variables expected by the SDK and the Claude Code CLI. This is critical for the unstable_v2_prompt function used in session management.

Config Field	Environment Variable
apiKey	ANTHROPIC_AUTH_TOKEN
baseURL	ANTHROPIC_BASE_URL
model	ANTHROPIC_MODEL

Sources: src/electron/libs/claude-settings.ts:75-83, src/electron/libs/util.ts:8-23

Application Usage Example: Session Title Generation

When a new session starts, the application uses the stored configuration to generate a title via the SDK.

// src/electron/libs/util.ts:25-45
export const generateSessionTitle = async (userIntent: string | null) => {
  const config = getCurrentApiConfig();
  const currentEnv = getEnhancedEnv(); // Merges process.env with config env

  const result = await unstable_v2_prompt(
    "prompt text...", {
    model: config?.model || "claude-sonnet",
    env: currentEnv,
    pathToClaudeCodeExecutable: getClaudeCodePath(),
  });
  // ...
};

Sources: src/electron/libs/util.ts:25-45

User Interface Interaction

The SettingsModal component provides the frontend interface for managing these settings. It interacts with the Electron main process via specific IPC handles defined in main.ts.

• get-api-config: Invoked on modal mount to populate fields with existing data.
• save-api-config: Invoked when the user clicks "Save", triggering the persistence logic.
• check-api-config: Used during application startup to determine if the user needs to be prompted for configuration immediately.

Sources: src/ui/components/SettingsModal.tsx:21-40, src/electron/main.ts:114-132, src/ui/App.tsx:103-116

Summary

The Configuration Store provides a robust, dual-source management system for API settings. By prioritizing local application settings while offering seamless fallback to standard CLI configurations, it ensures high compatibility and ease of use. It centralizes the validation and environment preparation logic, allowing other modules like session management and title generation to operate without direct knowledge of credential storage details.

Sources: src/electron/libs/config-store.ts, src/electron/libs/claude-settings.ts