Task Runner Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Task Runner Engine is the core execution layer of the Claude Cowork application, responsible for managing the lifecycle of AI-driven tasks. It orchestrates the communication between the user interface and the @anthropic-ai/claude-agent-sdk, enabling real-time streaming of AI thoughts, tool executions, and file system manipulations within a specific working directory.
This engine operates primarily within the Electron main process to handle sensitive system operations while providing asynchronous updates back to the React-based frontend. It ensures that API configurations, environment variables, and permission requests are correctly handled during a session.
Sources: src/electron/libs/runner.ts:1-12, src/ui/App.tsx:1-25, README.md:20-35
Core Architecture
The Task Runner Engine utilizes an asynchronous, event-driven architecture to bridge the gap between the local system environment and the Anthropic API.
Execution Flow
The engine initializes a query using the Claude Agent SDK, which returns an async iterator. This iterator allows the engine to capture and forward granular events such as system initialization, content block deltas (streaming text), and tool usage results.
Key Components
| Component | Responsibility | Location |
|---|---|---|
runClaude | Primary entry point for task execution; manages AbortController. | src/electron/libs/runner.ts |
query | SDK function that executes the LLM logic and tool orchestration. | @anthropic-ai/claude-agent-sdk |
generateSessionTitle | Analyzes user intent to create descriptive task names via AI. | src/electron/libs/util.ts |
RunnerHandle | Object returned to the caller to allow task cancellation. | src/electron/libs/runner.ts |
Sources: src/electron/libs/runner.ts:14-25, src/electron/libs/util.ts:24-35
Session Lifecycle Management
The engine manages tasks through a series of states: running, completed, and error.
Initialization
Before a task starts, the engine verifies the API configuration. If no configuration is found, it triggers an error status immediately. It also constructs an "enhanced environment" by merging system environment variables with specific API settings (e.g., Base URL, API Key).
Sources: src/electron/libs/runner.ts:44-55, src/electron/libs/util.ts:7-22
Interruption and Aborting
Tasks can be stopped manually by the user. The RunnerHandle provides an abort() method that triggers the AbortController linked to the SDK query, ensuring that network requests and local tool processes are terminated gracefully.
Tool Execution and Permissions
The engine facilitates "tool use," where the AI can perform actions like reading files or running bash commands.
Permission Handling
The engine is configured with bypassPermissions as the default mode for most tools but implements a specific interceptor for AskUserQuestion. When this tool is invoked, the engine generates a toolUseId and pauses execution, awaiting a response from the frontend via the permission.response IPC event.
Tool Types
Commonly supported tools within the engine include:
- Bash: Executing terminal commands.
- Read/Write/Edit: Local file system operations.
- WebFetch: Retrieving external web content.
Sources: src/electron/libs/runner.ts:71-95, src/ui/components/EventCard.tsx:162-175
Sources: src/electron/libs/runner.ts:71-100
Data Streaming and Rendering
To provide a responsive experience, the engine streams partial message deltas.
Stream Processing
- Content Block Start: Signals the beginning of a new message segment (text, thinking, or tool use).
- Content Block Delta: Provides incremental text updates which are accumulated and displayed in the UI with a "shimmer" loading effect.
- Content Block Stop: Finalizes the current segment.
Sources: src/ui/App.tsx:55-85, src/ui/components/EventCard.tsx:103-125
Visual Representation
The UI uses EventCard components to render various event types:
- Thinking: Displays the AI's internal reasoning process.
- Output: Shows tool results, often truncated with a "Show More" option if they exceed 3 lines.
- System Init: Summarizes session metadata like Model Name and Working Directory.
Sources: src/ui/components/EventCard.tsx:65-85, src/ui/components/EventCard.tsx:135-150
Conclusion
The Task Runner Engine provides the infrastructure required to run Claude as a persistent local collaborator. By bridging the Electron main process and the Claude Agent SDK, it enables complex workflows including file management and command execution while maintaining a transparent, real-time feedback loop through the streaming UI.