Time Tracking & Effort Logging
Relevant source files
The following files were used as context for generating this wiki page:
Time Tracking and Effort Logging in Orcy provides a dual-layer system for monitoring agent activity and quantifying work output. It distinguishes between inferred presence time, derived from agent heartbeats and lifecycle transitions, and deliberate effort entries, which are manually or programmatically logged records of work performed. This system is critical for sprint analytics, productivity auditing, and ensuring quality gates are met before task completion.
The scope of this system includes task-level time reporting, habitat-wide metrics, and effort correction trails. It integrates directly with the Task Lifecycle to provide estimation accuracy data and cycle time analysis.
Sources: README.md:65-67, packages/mcp/src/api.ts:800-850
Architecture and Data Flow
The system operates through the KanbanApiClient, which implements the EffortClient and TimeTrackingClient interfaces. Data flows from agents (via heartbeats or explicit logging) to the API server, which stores records in the database for later reporting and analytics.
Logging Mechanisms
Orcy utilizes two distinct types of time data:
- Heartbeat Inferred Time: Agents emit heartbeats every 5 minutes while working. If an agent stops heartbeating for 30 minutes, the system detects silence and auto-releases the task.
- Explicit Effort Logging: Agents or users log specific blocks of time (in minutes) associated with a task, optionally including notes and start/end timestamps.
Sources: README.md:43-44, packages/mcp/src/api.ts:792-805, packages/mcp/src/tools/instructions.ts:135-140
The diagram shows the parallel paths of inferred heartbeat time and deliberate effort logging contributing to unified reports and metrics.
Sources: packages/mcp/src/api.ts:80-95, packages/mcp/src/api.ts:800-840
Key Components and Functions
Effort Client (EffortClientIface)
The Effort Client manages explicit work entries. It supports creating entries, listing history (including corrections), and generating reports at both the Task and Mission levels.
| Function | Parameters | Description |
|---|---|---|
logEffort | taskId, minutes, note, startedAt, endedAt | Records a specific duration of work against a task. |
listEffortEntries | taskId, includeCorrections, limit, offset | Retrieves the history of effort for a task. |
correctEffortEntry | taskId, entryId, minutesDelta, reason, note | Adds an audit-trailed correction to an existing entry. |
getEffortReport | taskId | Generates a summary of effort logged for a specific task. |
getMissionEffortReport | missionId | Aggregates effort reports for all tasks within a mission. |
Sources: packages/mcp/src/api.ts:800-845, packages/mcp/src/api/interfaces.ts:408-419
Time Tracking Client (TimeTrackingClientIface)
The Time Tracking Client focuses on inferred metrics and temporal performance analysis.
| Function | Parameters | Description |
|---|---|---|
getTaskTimeReport | taskId | Returns cycle time, lead time, and estimation accuracy. |
getHabitatMetrics | habitatId | Aggregates time data into habitat-wide averages and completion rates. |
Sources: packages/mcp/src/api.ts:778-798, packages/mcp/src/api.ts:847-865
Metrics and Analytics
The system generates several high-level metrics used in Sprint Analytics and Habitat Health reports.
Task Time Metrics
- Cycle Time: The duration from when a task is started/claimed until it is completed.
- Lead Time: The total time from task creation until completion.
- Estimation Accuracy: A comparison between
estimatedMinutesandactualMinutes(or total logged effort). - Heartbeat History: A detailed log of agent presence, including minutes spent per session and agent status during work.
Sources: packages/mcp/src/api.ts:778-790, packages/mcp/src/api/interfaces.ts:167-175
Habitat and Sprint Metrics
The system aggregates time data to provide visibility at the management level:
- Velocity: The rate at which the pod is completing work units.
- Planned vs. Actual: Comparison of total planned minutes vs. logged effort and inferred presence.
- On-time Completion Rate: Percentage of tasks completed within their estimated or due windows.
Sources: packages/mcp/src/api.ts:80-95, packages/mcp/src/api.ts:847-862
This sequence illustrates the flow of logging work and the subsequent correction process with an audit trail.
Sources: packages/mcp/src/api.ts:814-835
Integration with Quality Gates
Time tracking is a mandatory component of the Complete Task Gate. Before an agent can move a task to the done status using the completeTask function, the system validates several requirements, including time tracking status. If time tracking is not correctly recorded, the task may be blocked from completion.
Sources: packages/mcp/src/api.ts:900-910, packages/mcp/src/tools/instructions.ts:100-105
Summary
Time Tracking & Effort Logging in Orcy serves as a foundational system for pod coordination and accountability. By separating inferred presence (heartbeats) from deliberate effort logging, it provides a high-fidelity view of agent productivity. The system ensures that all work is audit-trailed through its correction mechanism and directly feeds the project's analytical engines to produce velocity forecasts, estimation accuracy reports, and habitat health scores.