Path Resolution System
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Path Resolution System in Agent Cowork is a critical backend infrastructure responsible for locating internal application resources and external executable dependencies. Its primary purpose is to ensure that the application functions correctly across different execution environments—specifically differentiating between the local development environment and the final packaged production build.
The system handles three main categories of paths: internal Electron assets (preload scripts and UI files), application icons, and the critical @anthropic-ai/claude-agent-sdk CLI executable. By dynamically calculating these paths at runtime, the system maintains compatibility across different operating systems and installation structures.
Sources: src/electron/pathResolver.ts:1-24, src/electron/libs/claude-settings.ts:8-20
Core Path Resolution Logic
The path resolution logic is centralized in specialized utility functions that detect the application's state using Electron's app.isPackaged and the project's custom isDev() utility.
Internal Resource Mapping
Internal assets are mapped relative to the application's root directory. The system uses different offsets depending on whether the code is running from the source or a compiled distribution.
| Resource | Development Path | Production Path | Source Function |
|---|---|---|---|
| Preload Script | ./dist-electron/preload.cjs | ../dist-electron/preload.cjs | getPreloadPath() |
| UI Entry Point | /dist-react/index.html | /dist-react/index.html | getUIPath() |
| App Icon | ./templateIcon.png | ../templateIcon.png | getIconPath() |
Sources: src/electron/pathResolver.ts:6-24, src/electron/util.ts:7-9
SDK CLI Resolution
The system must resolve the path to the cli.js file within the @anthropic-ai/claude-agent-sdk package. This is essential for the unstable_v2_prompt functionality. In production, this file is located within the app.asar.unpacked directory to ensure the executable script remains accessible to the underlying OS.
Sources: src/electron/libs/claude-settings.ts:8-20, src/electron/libs/util.ts:28-40
Architecture and Data Flow
The following diagram illustrates how the Path Resolution System interacts with the Main process to provide correct paths for window initialization and external SDK calls.
This diagram shows the decision logic used to switch between development and production directory structures.
Sources: src/electron/pathResolver.ts:1-24, src/electron/libs/claude-settings.ts:8-20
Implementation Details
Path Resolution Functions
The system utilizes path.join and app.getAppPath() to build absolute paths, ensuring cross-platform compatibility (macOS, Windows, Linux).
// Example from src/electron/pathResolver.ts:6-12
export function getPreloadPath() {
return path.join(
app.getAppPath(),
isDev() ? './' : '../',
'/dist-electron/preload.cjs'
)
}
Sources: src/electron/pathResolver.ts:6-12
Integration with Window Creation
During the application startup in the main process, these resolved paths are used to configure the BrowserWindow and load the user interface.
The sequence shows the dependency of the window initialization on the path resolution functions.
Sources: src/electron/main.ts:61-75, src/electron/pathResolver.ts:14-16
Conclusion
The Path Resolution System provides a robust abstraction layer that shields the rest of the application from the complexities of Electron's file system differences between development and production. By centralizing this logic, the project ensures that assets and critical AI SDK components are reliably located regardless of how the application is deployed.
Sources: src/electron/pathResolver.ts:1-24, src/electron/libs/claude-settings.ts:8-20