Progress Tracking & Todos

Relevant source files

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

• renderer/renderer.js
• renderer/index.html
• README.md
• server/server.js
• renderer/style.css

The Progress Tracking & Todos system in Open Claude Cowork is a specialized module designed to provide real-time visibility into the agent's task execution. It functions as a dynamic to-do list that mirrors the internal state of the agent as it decomposes complex user requests into actionable steps. This system is integrated directly into the application's sidebar, allowing users to monitor which sub-tasks are pending, in-progress, or completed.

Sources: README.md:16, renderer/index.html:190-210, renderer/renderer.js:52-53

Architecture and Data Flow

The progress tracking system operates through a specialized tool called TodoWrite. When an agent processes a message, it can invoke this tool to update the list of tasks required to fulfill the user's request. These updates are streamed from the backend server to the frontend via Server-Sent Events (SSE) and immediately rendered in the UI.

Task Update Sequence

The following diagram illustrates how task updates flow from the AI provider through the backend to the user interface.

The frontend listens for specific tool_use events where the tool name is TodoWrite. Upon receiving these, it extracts the todos array from the tool input to synchronize the local state.
Sources: renderer/renderer.js:719-721, server/server.js:132, renderer/renderer.js:1071-1074

Data Structures and Components

Todo Object Schema

Tasks are managed as an array of objects within the application state. Each todo object typically contains information about its description and current status.

Field	Type	Description
content	String	The description of the task or step to be performed.
status	String	The current state: pending, in_progress, or completed.
activeForm	String	(Optional) Alternative display text used when a task is in progress.

Sources: renderer/renderer.js:1094-1100

UI Components

The progress interface is defined in the right sidebar of the application and consists of the following elements:

• Steps Header: Displays the current count of steps (e.g., "5 steps").
• Steps List Container: A scrollable area where individual task items are injected.
• Empty State: A placeholder (#emptySteps) displayed when no tasks are currently active.

Sources: renderer/index.html:194-206, renderer/renderer.js:35-38

Implementation Details

State Management

The renderer process maintains a global todos array. This array is populated during the message streaming process and is persisted as part of the chat session state in localStorage.

// renderer/renderer.js:53
let todos = [];

// renderer/renderer.js:1071-1074
function updateTodos(newTodos) {
  todos = newTodos;
  renderTodos();
}

Sources: renderer/renderer.js:53, renderer/renderer.js:1071-1074

Rendering Logic

The renderTodos() function dynamically generates HTML for each task. It assigns specific CSS classes based on the status field to apply visual cues (e.g., icons and animations).

The UI uses specific SVG icons to represent progress: a checkmark for completed and a circle for in_progress. The in_progress status also triggers a CSS pulse animation.
Sources: renderer/renderer.js:1077-1111, renderer/style.css:842-861

Persistence and History

Progress data is saved alongside message history to ensure that when a user returns to a previous chat, the task list is restored.

1. Saving: During the saveState() operation, the current todos array is included in the chatData object and stored in localStorage under allChats.
2. Loading: When loadChat(chat) is invoked, it restores the todos array from the saved chat object and calls renderTodos() to refresh the sidebar.

Sources: renderer/renderer.js:108, renderer/renderer.js:149, renderer/renderer.js:207

Summary

The Progress Tracking & Todos system provides a transparent view of the agent's internal roadmap. By utilizing the TodoWrite tool and SSE streaming, the application ensures that the UI remains synchronized with the agent's reasoning process, offering users immediate feedback on the status of complex, multi-step operations.