Feature: Native TaskList panel for Claude Code task tracking and agent team coordination

[mellanon]

Summary

Claude Code's TaskList system (TodoWrite / Tasks API) has evolved into central infrastructure for both individual task tracking and multi-agent team coordination. Maestro currently treats TodoWrite calls as generic tool execution events — showing a small tool badge with no dedicated UI. This proposal suggests surfacing TaskList as a first-class, inline-with-agent view in Maestro.

Background: How Claude Code's TaskList Works

Two Systems

Claude Code has two task management systems (Tasks API vs TodoWrite):

System	Storage	Persistence	Scope
TodoWrite (legacy)	In-memory (context window)	Session only	Single session
Tasks API (v2.1.16+)	~/.claude/tasks/<list-id>/ as JSON files	Permanent, cross-session	Namespace via CLAUDE_CODE_TASK_LIST_ID

The Tasks API supports dependency tracking (blockedBy), three states (pending/in_progress/completed), and file-locking for concurrent access.

Task List Scoping

Task lists are NOT per-folder — they're scoped by namespace:

• Default: Scoped by CLAUDE_CODE_TASK_LIST_ID environment variable
• Agent Teams: Scoped by team name — stored at ~/.claude/tasks/{team-name}/
• Single agents: Each agent may have its own in-memory TodoWrite list (session-scoped)

This means Maestro needs to be intelligent about linking task lists to the correct agent or team. A task list can be:

1. 1:1 with an agent — a single agent's TodoWrite working list
2. Shared across a team — the coordination layer for agent teams
3. Global by namespace — persistent tasks scoped by CLAUDE_CODE_TASK_LIST_ID

Agent Teams Coordination Layer

In Claude Code Agent Teams, the shared task list is the primary coordination mechanism between agents:

• Team lead creates tasks, teammates self-claim unassigned/unblocked tasks
• Tasks have dependency chains — blocked tasks auto-unblock when dependencies complete
• File locking prevents race conditions when multiple teammates claim simultaneously
• Task storage: ~/.claude/tasks/{team-name}/ (one directory per team)
• Team config: ~/.claude/teams/{team-name}/config.json

The task list is effectively the work routing layer — it's how agents discover what to do, signal completion, and unblock downstream work.

Current Maestro Behavior

Based on code analysis of the current codebase:

1. ClaudeOutputParser extracts tool_use blocks including TodoWrite from Claude's JSONL stream (src/main/parsers/claude-output-parser.ts)
2. StdoutHandler emits these as generic tool-execution events (src/main/process-manager/handlers/StdoutHandler.ts:321-328)
3. TerminalOutput renders a small tool badge — [TodoWrite] with a running/complete indicator (src/renderer/components/TerminalOutput.tsx:487-549)
4. The actual task list content appears only as rendered markdown in Claude's text output — no structured data extraction
5. TodoWrite is listed in KNOWN_TOOL_NAMES (src/renderer/constants/app.ts:22) but only for malformed output detection

No task state is tracked, no task progress is visualized, and no cross-session task persistence is surfaced.

Maestro's AutoRun system has its own separate checkbox-based task tracking (- [ ] / - [x] in markdown documents) which is completely independent from Claude Code's TaskList.

Proposal

UX Principle: Inline with Agent, Not Separate Panel

In Claude Code's terminal, the task list is always viewed in context of the agent — accessed via Ctrl+T as an overlay on the active session. Maestro should follow the same principle: task lists must sit with the agent, not in a separate menu or tab. A separate panel fragments attention and breaks the mental model.

Maestro's GUI advantage is that it can display this information more richly — but the contextual relationship between agent and task list must be preserved.

Phase 1: Inline TaskList Display

• Parse TodoWrite tool_use inputs to extract task items and their states (pending/in_progress/completed)
• Show task progress inline with the agent's terminal view:
  • Compact progress bar at the top or bottom of the AI Terminal showing N/M tasks complete
  • Expandable task list overlay (similar to Claude Code's Ctrl+T) showing individual task items with states
  • Real-time updates as Claude works through tasks
• The task list is contextually bound to the agent session — you see the tasks for whatever agent you're looking at

Phase 2: Persistent Tasks Integration

• Read ~/.claude/tasks/ directories to surface persistent task lists
• Detect task list scope: read CLAUDE_CODE_TASK_LIST_ID from session environment or detect team membership from ~/.claude/teams/
• Display dependency chains between tasks (blocked/unblocked state)
• Show task progress that persists across session restarts
• Maestro intelligently links the right task list to the right agent/session

Phase 3: Agent Team Task Coordination View

• When agent teams are active, show the shared task list with per-agent ownership badges
• Visualize which teammate owns which task, task dependencies, and completion flow
• Cross-agent awareness: click a task to jump to the agent session that owns it
• Dependency visualization showing blocked/unblocked chains
• Surface team config (~/.claude/teams/{team-name}/config.json) alongside task state
• This becomes the "mission control" view for multi-agent orchestration in Maestro

Data Model

TaskList (separate entity)
├── scope: 'session' | 'namespace' | 'team'
├── namespaceId?: string (CLAUDE_CODE_TASK_LIST_ID)
├── teamName?: string
├── tasks: Task[]
│   ├── id, content, status (pending/in_progress/completed)
│   ├── owner?: string (agent name for team tasks)
│   └── blockedBy?: string[] (dependency tracking)
└── linkedAgents: AgentSession[] (1:1 or 1:many)

UI Rendering:
- Always inline with agent terminal view
- Progress bar + expandable overlay (not separate tab/panel)
- Team view: ownership badges, cross-agent click-to-jump

Why This Matters

The TaskList is evolving from a simple progress display into the coordination substrate for Claude Code's multi-agent architecture. As agent teams become more common, the task list becomes the primary way to understand what a swarm of agents is doing, who owns what, and what's blocked. Maestro is uniquely positioned to provide this visibility since it already manages multiple concurrent agent sessions.

Related: #340 (Claude Agent SDK integration) would provide typed access to these events, making structured TaskList parsing significantly easier.

References

• Claude Code Agent Teams docs
• Tasks API vs TodoWrite
• Multi-Session Task Coordination
• Claude Code Tasks update (VentureBeat)
• Todo Lists - Claude API Docs

[pedramamini]

Ah, interesting. These are exposed by a disk. That's good to know. This is first of all one way I can validate whether or not the agent teams are working versus sub-agents. Furthermore, this gives us an opportunity for some introspection of what's going on in the tasks between agents.

I'm struggling with the thought of adding something specific to Claude Code as a UX feature. Maybe instead, what we can do is have some form of implementation within the message history where we will examine the tasks and show them in the message history. That way, it still remains generic UX-wise.

Something to discuss.