feat: add activity timeline / event log to track taskmaster actions #73

New issue

Open

opened 2025-10-14 15:40:37 -06:00 by navan · 0 comments

navan commented

2025-10-14 15:40:37 -06:00

Owner

Originally created by @DevSuyashA on 9/23/2025

“As a user opening a fresh chat or editor session, I want Task Master to instantly tell me the last thing it worked on (and the recent sequence of actions) without diffing files or manually cross-referencing tasks.”

Motivation

Today, after Task Master modifies a project (via CLI or MCP), there’s no canonical, queryable timeline of events. In a new session I can’t simply ask “what was just worked on?”—I have to infer from code diffs and task files, or scan commands like list, next, etc. This is slow and brittle.

A first-class Activity Timeline / Event Log would let Task Master (and its editor integrations) answer timeline queries immediately across both CLI and MCP workflows. This fits the project’s documented CLI + MCP architecture and .taskmaster project layout.

Proposed Solution

Introduce a durable, append-only Activity Timeline that records Task Master actions with timestamps, session IDs, and task references.

High-level overview
- Write structured JSONL events to .taskmaster/log/timeline.jsonl whenever core actions occur (e.g., parse-prd, add-task, update-task, expand, generate, set-status, dependency ops).
- Add CLI commands to query: task-master last, task-master timeline.
- Add MCP tools to fetch the last activity and recent history for editor/agent UIs.
Relevant technologies / integrations
- File-based append-only JSONL (+ optional gzip rotation).
- Hook into existing task-manager.js (called from MCP tools) and core CLI commands so both surfaces emit the same events.
Fit with existing workflow/architecture
- Resides under .taskmaster/ alongside existing project artifacts and task files; does not replace tasks.json (task model remains source of truth for planning/status).

High-Level Workflow

Logger module: Create packages/core/activity-logger.ts (or similar) with logEvent() that appends JSONL and handles rotation.
Emit hooks: At the start and completion of each core command/tool, emit *.started and *.completed|failed events (with duration).
CLI surface:
- task-master last [--task <id>] [--json]
- task-master timeline [--since 2h] [--limit 50] [--task <id>] [--json]
MCP tools (under mcp-server/src/tools):
- get_last_activity(taskId?)
- get_timeline(since?, limit?, taskId?)
  These proxy to the same reader used by the CLI.
(Optional) VS Code/Editor UI: Extensions can render a “Recent Activity” panel fed by the MCP tools/file, complementing existing Task Master UI surfaces.

Key Elements

Event schema (v1)
- schema: "taskmaster.activity.v1"
- timestamp (ISO), eventId (ULID), sessionId, workspace
- actor ("taskmaster" | "user"), command (e.g., "update-task"), action (phase: *.started|completed|failed)
- task: { id, title? }
- inputs (flags/prompt hash), result (status, durationMs, notes)
- artifacts (e.g., files touched), optional git metadata
Config
- .taskmaster/config.json: "activityLog": { "enabled": true, "maxSizeMB": 10, "redact": true }
CLI UX
- Human-readable default, --json for programmatic use.
MCP
- New tools registered in mcp-server/src/tools/index.js with zod validation, mirroring existing pattern.
Privacy
- Local-only by default; redact obvious secrets (envs, tokens).

Example Workflow

# Do normal work
$ task-master add-task --prompt "Add OAuth callback route with CSRF protection"
→ Created task 17: "OAuth callback route"

$ task-master expand --id 17 --num 3
→ Added 3 subtasks to task 17

$ task-master set-status --id 17 --status in-progress
→ Task 17 marked as in-progress

# Now query the timeline
$ task-master last
2025-09-24 12:34:59 ✓ set-status T-17 "OAuth callback route" (in-progress)

$ task-master timeline --since 2h --limit 5
12:34:59 ✓ set-status T-17 in-progress
12:34:12 ✓ expand     T-17 added 3 subtasks
12:33:02 ✓ add-task   T-17 "OAuth callback route"

Implementation Considerations

Dependencies: None external; Node fs + gzip for rotation.
MCP parity: Tools call the same reader; keep emitted events consistent whether invoked via CLI commands or MCP tools.
Backward compatibility: Default on for new projects; existing projects opt-in via task-master init --enable-activity-log or manual config toggle.
Performance: JSONL append is O(1); rotation at size threshold; reading supports --since/--limit to avoid loading large files.
Backfill: Optional task-master timeline backfill synthesizes coarse events from recent git log and tasks.json to seed history (flag outputs as "synthesized": true).

Out of Scope (Future Considerations)

Cross-machine or remote timeline sync.
Rich cost/usage telemetry in events (might be gated by config later).
Real-time streaming UI; initial version is file + simple readers.
Automatic correlation with editor extensions beyond MCP tools (can be implemented later by VS Code/other UIs).

*Originally created by @DevSuyashA on 9/23/2025* > “As a user opening a fresh chat or editor session, I want Task Master to instantly tell me the **last thing it worked on** (and the recent sequence of actions) without diffing files or manually cross-referencing tasks.” ### Motivation Today, after Task Master modifies a project (via CLI or MCP), there’s no canonical, queryable **timeline of events**. In a new session I can’t simply ask “what was just worked on?”—I have to infer from code diffs and task files, or scan commands like `list`, `next`, etc. This is slow and brittle. A first-class **Activity Timeline / Event Log** would let Task Master (and its editor integrations) answer timeline queries immediately across both **CLI** and **MCP** workflows. This fits the project’s documented CLI + MCP architecture and `.taskmaster` project layout. ### Proposed Solution Introduce a durable, append-only **Activity Timeline** that records Task Master actions with timestamps, session IDs, and task references. - **High-level overview** - Write structured JSONL events to `.taskmaster/log/timeline.jsonl` whenever core actions occur (e.g., `parse-prd`, `add-task`, `update-task`, `expand`, `generate`, `set-status`, dependency ops). - Add **CLI** commands to query: `task-master last`, `task-master timeline`. - Add **MCP tools** to fetch the last activity and recent history for editor/agent UIs. - **Relevant technologies / integrations** - File-based append-only JSONL (+ optional gzip rotation). - Hook into existing `task-manager.js` (called from MCP tools) and core CLI commands so both surfaces emit the same events. - **Fit with existing workflow/architecture** - Resides under `.taskmaster/` alongside existing project artifacts and task files; does not replace `tasks.json` (task model remains source of truth for planning/status). ### High-Level Workflow 1. **Logger module**: Create `packages/core/activity-logger.ts` (or similar) with `logEvent()` that appends JSONL and handles rotation. 2. **Emit hooks**: At the start and completion of each core command/tool, emit `*.started` and `*.completed|failed` events (with duration). 3. **CLI surface**: - `task-master last [--task <id>] [--json]` - `task-master timeline [--since 2h] [--limit 50] [--task <id>] [--json]` 4. **MCP tools** (under `mcp-server/src/tools`): - `get_last_activity(taskId?)` - `get_timeline(since?, limit?, taskId?)` These proxy to the same reader used by the CLI. 5. **(Optional) VS Code/Editor UI**: Extensions can render a “Recent Activity” panel fed by the MCP tools/file, complementing existing Task Master UI surfaces. ### Key Elements - **Event schema (v1)** - `schema`: `"taskmaster.activity.v1"` - `timestamp` (ISO), `eventId` (ULID), `sessionId`, `workspace` - `actor` (`"taskmaster"` | `"user"`), `command` (e.g., `"update-task"`), `action` (phase: `*.started|completed|failed`) - `task`: `{ id, title? }` - `inputs` (flags/prompt hash), `result` (`status`, `durationMs`, `notes`) - `artifacts` (e.g., files touched), optional `git` metadata - **Config** - `.taskmaster/config.json`: `"activityLog": { "enabled": true, "maxSizeMB": 10, "redact": true }` - **CLI UX** - Human-readable default, `--json` for programmatic use. - **MCP** - New tools registered in `mcp-server/src/tools/index.js` with `zod` validation, mirroring existing pattern. - **Privacy** - Local-only by default; redact obvious secrets (envs, tokens). ### Example Workflow ```shell # Do normal work $ task-master add-task --prompt "Add OAuth callback route with CSRF protection" → Created task 17: "OAuth callback route" $ task-master expand --id 17 --num 3 → Added 3 subtasks to task 17 $ task-master set-status --id 17 --status in-progress → Task 17 marked as in-progress # Now query the timeline $ task-master last 2025-09-24 12:34:59 ✓ set-status T-17 "OAuth callback route" (in-progress) $ task-master timeline --since 2h --limit 5 12:34:59 ✓ set-status T-17 in-progress 12:34:12 ✓ expand T-17 added 3 subtasks 12:33:02 ✓ add-task T-17 "OAuth callback route" ``` ### Implementation Considerations - **Dependencies**: None external; Node fs + gzip for rotation. - **MCP parity**: Tools call the same reader; keep emitted events consistent whether invoked via CLI commands or MCP tools. - **Backward compatibility**: Default **on** for new projects; existing projects opt-in via `task-master init --enable-activity-log` or manual config toggle. - **Performance**: JSONL append is O(1); rotation at size threshold; reading supports `--since/--limit` to avoid loading large files. - **Backfill**: Optional `task-master timeline backfill` synthesizes coarse events from recent `git log` and `tasks.json` to seed history (flag outputs as `"synthesized": true`). ### Out of Scope (Future Considerations) - Cross-machine or remote timeline sync. - Rich cost/usage telemetry in events (might be gated by config later). - Real-time streaming UI; initial version is file + simple readers. - Automatic correlation with editor extensions beyond MCP tools (can be implemented later by VS Code/other UIs).