Settings & Modals
Relevant source files
The following files were used as context for generating this wiki page:
The Settings & Modals system in Agent Cowork provides the primary interface for administrative configuration, session initialization, and interactive user permissions. These components are implemented as React functional components that utilize Electron's Inter-Process Communication (IPC) to bridge frontend user inputs with backend persistence and the Claude Agent SDK.
The system encompasses three primary modal/panel types: the SettingsModal for API configuration, the StartSessionModal for launching new tasks, and the DecisionPanel for handling real-time permission requests and questions from the AI agent.
API Configuration & Settings Management
The SettingsModal acts as the configuration hub for the application, allowing users to define the parameters required to connect to Anthropic or compatible third-party APIs. It handles the lifecycle of API configuration including loading existing settings, validation, and secure persistence via the Electron main process.
Configuration Data Flow
When the modal initializes, it triggers a request to the main process to fetch existing configurations. Upon saving, it validates the input (checking for required fields and URL formats) before sending the data back to be stored in the local file system.
The diagram shows the lifecycle of API configuration from initial fetch to validated persistence.
Sources: src/ui/components/SettingsModal.tsx:21-78, src/electron/main.ts:117-133
Key Settings Parameters
| Parameter | Type | Description | Source |
|---|---|---|---|
apiKey | string | The authentication key for the Anthropic/Third-party API. | src/ui/components/SettingsModal.tsx:8 |
baseURL | string | The endpoint URL for the API (e.g., https://api.anthropic.com). | src/ui/components/SettingsModal.tsx:9 |
model | string | The specific AI model identifier (e.g., claude-3-5-sonnet). | src/ui/components/SettingsModal.tsx:10 |
apiType | string | Fixed to "anthropic" for compatibility with the SDK. | src/ui/components/SettingsModal.tsx:61 |
Session Initialization
The StartSessionModal is the entry point for creating new AI collaboration tasks. It allows users to define the environment (Working Directory) and the initial instruction (Prompt) for the agent.
Directory Selection and History
The system supports both manual path entry and a native directory picker via Electron's dialog.showOpenDialog. It also displays a list of recently used directories fetched from the session history database.
The flow depicts how a user selects a working environment and provides task context to initialize a session.
Sources: src/ui/components/StartSessionModal.tsx:1-40, src/electron/main.ts:101-115
Implementation Details
The modal uses the window.electron.selectDirectory() and window.electron.getRecentCwds() IPC handlers to interact with the host operating system and local SQLite storage.
Sources: src/ui/components/StartSessionModal.tsx:23-26, types.d.ts:28-34
Interactive Decision and Permission Panels
The DecisionPanel (rendered via the EventCard system) manages the interactive layer between the Claude Agent and the user. It is invoked when the agent requires explicit permission to use a tool or needs to ask the user a structured question.
Permission Request Logic
When the agent attempts to use tools like Bash, Write, or Edit, the system intercepts the request and displays the DecisionPanel. Users can inspect the raw input (command, file path, etc.) before allowing or denying the action.
This diagram illustrates the gatekeeping mechanism for sensitive agent tools.
Sources: src/ui/components/DecisionPanel.tsx:142-167, src/ui/App.tsx:210-214
User Questions (AskUserQuestion)
The DecisionPanel also handles the AskUserQuestion tool, which supports complex UI elements like headers, options, and multi-select inputs.
| Feature | Description | Implementation |
|---|---|---|
multiSelect | Allows users to pick multiple pre-defined options. | src/ui/components/DecisionPanel.tsx:50-58 |
Other Input | Text field for custom answers not in the option list. | src/ui/components/DecisionPanel.tsx:106-115 |
| Auto-Submit | Submits immediately if there is only one non-multi-select question. | src/ui/components/DecisionPanel.tsx:88-97 |
Global State and Modal Control
Modal visibility is managed through the useAppStore (Zustand) and coordinated within the root App.tsx component. This ensures that modals like the SettingsModal can be triggered automatically (e.g., if no API config is found at startup) or manually via the sidebar.
The state management logic determines when specific modals are rendered based on application readiness and user interaction.
Sources: src/ui/App.tsx:128-142, src/ui/components/Sidebar.tsx:75-87
Summary
The Settings & Modals system provides the critical infrastructure for secure API management, structured session launching, and safe tool execution through user-in-the-loop decision panels. By leveraging IPC and centralized state, the application maintains a consistent configuration across the UI and the Claude Agent SDK.