Task Graph and Projects Activity view

The Task Graph shows what each coding agent is doing, as a tree of tasks and steps per session. Open Task Graph from the console menu. Projects, Sessions and Mosaic rows also show each session's latest step and checklist progress. TUI, web and desktop use the same screens.

Control Room sessions (Control Room chats and their operator and task-pool executions) are not part of the Task Graph. GET /v1/agent-tasks leaves them out, so the Task Graph screen, Projects Activity tiles, session step rows, the not reporting marker, unknown-step statistics and peer get_project_task_graph results never show them. Their stored reports are kept, and their MCP results and runtime guide carry no reporting guidance.

Where the data comes from

Two sources feed one session-scoped tree:

Each report_agent_task and list_agent_tasks result carries nativeStepCapture and guidance. Sessions whose hooks reported events are told to declare one top-level task per user request before their first tool call (hooks see tool calls, never what the work is) and otherwise report only phases, waits, blockers and completion; sessions without native capture (agent CLIs without devctl hooks, or a session whose hook never reported) are told to report every meaningful step when it starts and ends. A declared task that repeats a hook step of the same agent (same title within five minutes) replaces it, and a hook step that repeats the agent's open declared task joins it, so a step appears once. The Task Graph marks sessions without native capture as MCP reports only and lists a running session that is not known to be idle and has reported nothing for ten minutes as not reporting (an open native step, such as a long test run, does not count as silence).

Step types and their one-line definitions (the same text is in the report_agent_task stepType schema and the runtime guide):

Type Emoji ASCII Meaning
plan πŸ“‹ pl decide the approach, break work into steps, update a checklist
research πŸ” rs read code, docs, logs or the web to understand something
edit πŸ“ ed change source, config or content files
install πŸ“₯ in add, update or remove dependencies or tools
build 🧱 bd compile, bundle or build images
run πŸƒ rn run a program or script that is not a test, build or lint
test πŸ§ͺ ts run or write tests
lint 🧹 ln run linters, formatters or type checks
debug πŸ› dg reproduce and diagnose a failure
review πŸ‘€ rv review code, a diff or a pull request
git 🌿 gt commit, branch, merge, rebase or push
deploy πŸš€ dp release, publish or deploy
docs πŸ“š dc write or update documentation
coordinate 🀝 co delegate to or message subagents and other sessions
wait_input πŸ™‹ wi wait for the user's answer or approval
wait_external ⏳ we wait for CI, a service, a timer or another process
cleanup 🧽 cl remove temporary files, processes or resources
configure πŸ”§ cf change settings, permissions, network or environment configuration
request πŸ”‘ rq ask the operator or Control Room for access, resources or approval
other πŸ“¦ ot a declared value devctl does not know
unknown ❓ ?? no type declared; shown with its label

Generic reads and runs refined by their shell label use 🌐 nw (network), πŸ’Ύ db (database) and 🐳 ct (containers). The table and its lookups are stepCategoryEmoji, stepCategoryAscii, stepCategoryIcon(task), stepCategoryGlyph(id) and stepGroupIcon(kind) in apps/tui/src/step-category-icons.ts; every emoji has default emoji presentation, no VS16 or ZWJ, and is exactly two columns wide.

A step's type comes only from the agent's declaration or from the structured identity of a native tool call, never from text:

An unknown step carries a free-text label; the Task Graph screen shows statistics of these labels (and of other values) so missing types can be identified. The console leaves out labels that are a known tool's own name (rows an earlier hook stored as unknown, such as clocksleep), typed with the same tool mapping. Labels that name only an MCP server (mcp:notion recorded without its tool, mcp:devctl for a control_request recorded without its operation) carry no tool identity and stay unknown.

The session plan

A session reports its plan as one tree with devctl update_session_plan; every call replaces the tree. goal (title and an optional note) says why the work exists and leads the session's header; it may carry spend and eta of its own. Money or quota is the spend of the node it belongs to (the goal or the item that spends it), never a node of its own. items are what the agent does for it, each with a state (running, queued, done, blocked, waiting-for-user, proposed), optional progress ({done, total}), eta, spend and note, and children for its steps: at most four levels including the goal and 60 nodes. A short key keeps an item's identity when its title changes; without it the title path is the identity.

Core stores the tree as real tasks of the session (source mcp, nativeRef plan:goal and plan:<path>, the goal as the root and items by parentTaskId), in fields every console reads: running β†’ running, queued β†’ pending, done β†’ completed, blocked β†’ blocked, waiting-for-user β†’ waiting with step type wait_input, proposed β†’ pending with step type request; progress β†’ progress.completed/total, note β†’ summary, eta and spend β†’ detail. One transaction upserts the reported nodes, removes the ones no longer reported and keeps a node's updatedAt when it did not change (so a stale item can be told from a current one). Each replacement is a revision; the last ten trees are kept in integration_state (agent-plan:<session>). New siblings list in reported order. The plan is the session's tree, never a turn's sentence.

The story view shows the goal as the session's headline with its spend, then the work's own state and what it needs from the user, then the agent's input state (Re-check published rules Β· $46 of $200 Β· ⟳ work runs in the background Β· βš‘ 1 item needs you Β· ? waiting for your input): the prompt wait is the agent's, not the work's. Under it the tree: state glyph (⟳ running, β—· queued, βœ“ done, β€– blocked, ? waiting for you, β—‡ proposed), title, progress, ETA/spend and note; a done branch folds its steps (Enter opens it). The turns move behind one β–Έ N turns of history row. Without a reported plan the story is unchanged, with a dim no plan reported hint.

The reminder. The managed guide asks agents to keep the plan current. The lifecycle hook (Claude Code and Codex run the same script) also asks once: at the main agent's Stop after a turn that did work (at least three shell calls, or an edit, or a subagent) without an update_session_plan call, it answers the Stop with {decision: "block", reason} naming the tool. It never asks when the provider marks the Stop as a continuation (stop_hook_active), a second time in the same turn (recorded in devctl-plan-reminder.json before it asks), for devctrl's delivered notices or the provider's background-task notifications, for a turn that used a Control Room tool, or where the launch left devctl-plan-reminder.off (evidence-only sessions and sessions without devctl MCP). A blocked Stop is not recorded as the turn's end. Running sessions get it with the next in-place hook upgrade.

The story view

The Task Graph opens on the story of each session, so the operator can tell what is happening without asking. One row per conversation turn, newest first, under a Now line:

β–Ά Now: working on β€œfind the approval number” since 23:05 Β· running: node find-approval.mjs Β· 6m Β· latest answer: β€œWaiting for approval 42 to finish.”
β–Έ ● Rebuilt the market report; 15 rows still need manual review. Β· 21:00 Β· 30m
    πŸ’¬ Implement market analytics
    edited report.ts Β· 1 commit Β· 2 errors Β· 4 commands Β· 6 steps (Enter)
β–Έ πŸ”” devctrl: access update Γ—7 Β· 21:56–21:59

Free text of the story (the user's message, the answer, the turn's sentence and command summaries) is returned only to viewers with terminal access to the session, like prompts. Task Graph-only shares, public links and external MCP clients see the same rows with the digest, notices, exit codes and durations, but without any of that text.

The Decisions sentence is the last resort for a finished turn with neither a declaration nor an answer (an interrupted turn, or a provider version without the Stop field). The Decisions API answers choice questions only, so Core offers the owner's configured Decisions model a few candidate sentences built from the turn's structured facts (its digest and the user's message) and stores the one the model picks on the turn. Nothing is classified by text. It runs only for finished turns of the last 24 hours, at most 12 calls per ten minutes and one per session every two minutes, each turn at most once; the owner's Decisions budget is checked and reserved like any other Decisions request, and nothing is asked while the Decisions route is not configured or not published to the owner. A turn is finished when the agent's Stop ended it, when the next turn of the session started, or when the session's structured lifecycle has been idle since the turn started (the provider hook's waiting-for-input state, or an exited or failed process) for two minutes: most sessions started with an older hook record no Stop, and the newest turn of a session has no next turn, so without the idle rule a session's last turn was never asked about. devctrl's own envelope turns are never asked about. A turn without any source shows its digest sentence.

Commands in the step view

A run step says what it did: the agent's own description of the call (Claude Code's Bash description, Codex's justification), else a short command summary from the hook's structured argv: program, subcommand or script and a few arguments (node build-report.mjs, pnpm test api, git push origin main), with paths reduced to file names, URLs to their host, quoted text and long values to … and secret-looking values or the values of secret-named options redacted, at most 80 characters. Its outcome follows: βœ“ or βœ— exit N when the provider reported an exit code in the PostToolUse response, and the call's duration. Consecutive identical calls fold as Γ—N only when their command summaries are identical, never because they ran the same program. Codex apply_patch steps name the files from the patch's own headers.

Step descriptions

Native steps are titled with the text the agent already writes: the Bash and Task description, the checklist item's activeForm, the search query, the fetched host, or a verb plus the file's basename for file tools. The step type and shell label become a badge. Text is sanitized in the hook before it is written: URLs keep only the host, paths only the basename, secret-looking values are redacted and each text is capped at 100 characters. Raw commands, environment values and transcripts are never recorded; the bounded command summary of a shell step (above) is shown only to viewers with terminal access.

Each step starts with an emoji for its step type (two columns wide, for example πŸ”Ž research, πŸ§ͺ test, πŸ“ edit). Consecutive steps of the same agent with the same step type and label fold into one group row, such as β–Έ ● πŸ”Ž [research: grep] Γ—2 Β· completed Β· 16:34–16:33 Β· 17s: its count, the newest and oldest start times, the summed duration and its status (a failed or blocked step wins, otherwise the newest step's status). Groups use only the structured step type and label, never the titles. A single step stays ungrouped. β†’ opens a group and ← folds it again.

Signal and noise

The graph leads with what the agent is doing, not with its mechanics. All of this uses structured step fields only (source, step type, classifier label, tool name, poll mark, status and times), never titles or other free text:

x (Russian layout: Ρ‡) shows every step: routine steps (including devctl bookkeeping calls) and idle loops are listed as recorded.

Each new turn of the main agent adds a πŸ’¬ input turn row at the top of the steps it caused. It comes from the hook's UserPromptSubmit (Claude Code and Codex both fire it) and, when a hook missed the turn, from a structured turn-started observation; one turn within 15 seconds is one row. The hook keeps only the prompt's first non-empty line, sanitized like other step text (URLs keep the host, paths the basename, secret-looking values are redacted) and cut to 200 characters; terminal text is never parsed. That line is shown as πŸ’¬ <prompt> only to viewers with terminal access to the session: its owner and users the terminal is shared with. Task Graph-only shares, public links and external MCP clients get the row without the text, as πŸ’¬ input turn. The row shows "agent working" until the agent's next step and ends the wait before it at the moment the input arrived. Turns whose prompt repeats (a scheduled wake-up) can still fold into an idle loop; a new message breaks the loop.

Steps are grouped under the checklist item that was running. Finished items and subagents fold into a summary of what was done below them: counts by kind of work, most frequent first (for example reads Γ—10, tests Γ—5, git Γ—3, database Γ—2), and the latest two step descriptions. Generic reads and runs are refined by their shell label into network, database and container work.

Timings and details

Every row shows its local start time and a duration that keeps counting while the step runs. The details view adds a timeline of recent steps and the agent's checklist.

Project tree and activity markers

The Task Graph is one pane: a single tree with the Projects tree's levels β€” project group (shown in capitals), repository, container (↳ main), session and, in the by-agent view (g), each session's agent lanes β€” with the session's tasks below. Within a session or lane the newest work is on top at every level, and the cursor starts on the newest task.

Navigation is the Projects tree's: Up/Down move among rows of the selected level only (across parents), Right opens a folded node and moves to its first child, and Left moves to the parent and folds it. Enter on a group, repository, container, session or lane scopes the view to it; a breadcrumb line (Showing: Shop β€Ί Api β€Ί main β€Ί alpha) names the scope and the levels above it, which are left out of the tree. Esc climbs one level, c shows every session again, and / searches group, repository and session names and task titles in the scope (Up/Down step through matches, Enter keeps the match, Esc closes the search). The Conversations and Reviews sections appear for a session or agent in scope. The tree uses the Projects tree order and lists the sessions the graph lists.

Every node carries activity markers from a closed set. Core derives them from structured state only β€” never from agent-written text β€” per session, then merges them (deduplicated, most severe first) into the repository and group. GET /v1/agent-tasks returns them additively as sessions[].tags, sessions[].groupId and the groups[] / projects[] scope lists. Ids are stable and are the keys for web icons:

Id Glyph Source
failed βœ— Session status or provider-hook lifecycle failed
needs-approval βš‘ Lifecycle waiting_approval, or an unexpired pending MCP approval of the session
waiting-input ? Running session with lifecycle waiting_input
blocked β€– An open reported task with status blocked
quota ⏳ Quota recovery whose reset is still ahead, or model-capacity retry scheduled/running
conflict ⇄ Repository only: Exchange conflict set not yet dismissed at its current count
not-reporting … The existing not reporting rule
review β—Ž Work status marked as requiring review
frozen ❄ Session freeze in progress, frozen or thawing
outdated-cli ↑ Running session launched with a CLI older than the latest managed release
working ● Running session with lifecycle working or a running reported task

New ids may be added; existing ids are never renamed or reused.

A turn row counts as a running task only until it ends: the agent's Stop completes it. Before, a turn stayed running until the main agent's next step, and a turn shorter than the Host's lifecycle sampling (a background-task notification answered in seconds) never got one, so a session waiting for input kept working and its project and group rows a spinner. Rows an earlier Core left running after their Stop are completed once at startup (agent-task-reports:ended-turns:1). A shell step also ends at its PostToolUse (it used to record only the exit code), and the Stop ends the main agent's other open steps of that turn; steps an earlier Core left open after their turn's Stop are completed once at startup (agent-task-reports:ended-turn-steps:1). The implicit Session activity root, which stays running for the session's life, never counts as a running task (the Projects summaries already left it out; the Task Graph counted it while it was among the listed rows, so a young session always looked busy).

Work kinds and work markers

Each session row also says what the session is working on and what it has done, like a task list: its declared work kind before the name, then work markers, the pull request number and how long ago it last reported (✦ alpha βš‘β— βœ“β‡£ #3981 18m). The graph's session header spells them out with the task title. GET /v1/agent-tasks returns them additively as sessions[].work (kind, title, pullRequest, markers[] with id, source and at, updatedAt). Nothing is inferred from agent-written text:

Of tests-*, build-*, ci-* and committed / pushed, only the latest marker of each pair is current. At most 12 markers are returned, newest first.

Work kind Glyph
feature ✦
bugfix ✚
refactor ↻
tests βœ“
docs ΒΆ
review β—Ž
release ⚐
investigate βŒ•
plan ☰
ops βš™
Marker Glyph Source
tests-passed βœ“ agent
tests-failed βœ— agent
build-passed β–£ agent
build-failed β–’ agent
committed β—† git, or agent without a git status
pushed ⇑ git, or agent without a git status
pr-opened β‘‚ agent
ci-passed βœ” agent
ci-failed ✘ agent
deployed βš‘ agent
uncommitted Β± git
unpushed ⇣ git

Ids are stable icon keys; new ids may be added, existing ids are never renamed. Core has no pull request or CI provider integration yet, so pr-opened, ci-* and the pull request number come only from agent reports.

Projects Activity view

Activity is a third Projects layout next to the list and the mosaic. Select it from the Projects view tabs or save it as the Projects layout preference. It uses the same tile grid, session set, groups and navigation as Mosaic, but each tile shows the session's current work, checklist progress and the latest rows of its work tree instead of its terminal. The graph is polled only while the view is visible, and terminal previews are not fetched for Activity tiles.

Projects Task Graph view

Task Graph is a Projects layout next to the tree, the session mosaic, Activity and Project Agents. It uses the mosaic's tabs, groups, hidden sessions and order; each tile shows one session's compact graph:

Arrows move between tiles as in the mosaic. Enter opens the full Task Graph scoped to that session with all of its keys (g, m, v, /, the breadcrumb); Esc at that scope returns to the mosaic on the same tile. The browser shows an Open task graph button on each tile. The choice of view is saved with the other Projects layouts.

Tiles poll GET /v1/agent-tasks/summaries every five seconds for the sessions of the current tab only, and only while the tiles are visible. The summaries are bounded (at most 12 recent tasks and 8 lanes per session, 200 sessions); counting happens in Core's database, and no session's full graph is fetched for a tile. An entered tile reads the full graph like the Task Graph screen.

API and authority

Method Route Purpose
GET /v1/agent-tasks The signed-in user's task graph across owned sessions
GET /v1/agent-tasks/summaries Bounded per-session summaries for Projects Task Graph tiles
GET /v1/agent-tasks/unknown-steps Statistics of unknown step labels
PUT /v1/agents/:id/sessions/:sessionId/task-graph Native hook snapshots forwarded by the session's own Host agent

/v1/agent-tasks accepts optional sessionId, projectId and limit filters and returns only sessions owned by the caller; its sessions carry workspaceId and workspaceName for the container level. /v1/agent-tasks/summaries accepts sessionIds (comma-separated, at most 200) and recent (1–12, default 6) and also covers only owned sessions. External OAuth clients can read the same data for granted Projects through get_task_graph with the tasks:read scope; see External MCP clients.

Reports are unverified progress claims. They grant nothing, do not verify results, do not change session state and do not replace report_session_handoff. Each session is limited to 500 tasks and a depth of 16. Concurrent hooks journal their events atomically, so parallel tool calls do not overwrite each other's steps.

Hook upgrades for running sessions

The hook script is read by the agent CLI on every event, so an updated hook applies to running sessions without a restart:

The set of hook events the CLI calls is fixed when the session starts. The events the task graph needs (PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop) have been registered since the Task Graph was introduced, so older running sessions gain the new classification, subagent matching and outcomes after the upgrade. Steps recorded before the upgrade keep their old titles and categories.

Conversations between sessions

GET /v1/agent-tasks also returns conversations (newest first, at most 200, with conversationsTruncated) for the listed sessions. Each event comes from a structured record only:

Kind Source Status
message, question, answer Project messages sent by or delivered to a listed session delivered, read, expired, rejected; a question is pending until an answer replies to it, then answered
delegation delegate_task records owned by the user running, completed, failed
handoff report_session_handoff reports completed
any of the above requests held by the peer-payload check held

Bodies are never returned. The only text is the subject, or the first line of the body, redacted and cut to 120 characters; held requests carry no text at all. A sender on a paired Core is shown by its handle and Core id only, and an unlisted recipient by its existing message handle.

In Task Graph each session ends with a "Conversations" section showing its newest eight events: β†’ sent, ← received, then the kind (βœ‰ message, ? question, ↩ answer, β‡’ delegation, ⎘ handoff), the other side, the subject and the status; a handoff recorded twice with the same subject, sides and status is listed once. Waiting questions and held requests are highlighted. A task that links a message thread shows βœ‰ β†’sent ←received ?waiting βœ“answered for that thread. Selecting a conversation with another listed session and pressing Enter scopes the graph to that session. m hides or shows conversations; the choice is remembered with the other view preferences.

A task can declare up to eight links with report_agent_task links, IDs only: a Project message thread ({kind:"thread", threadId}), a Project board item ({kind:"board_item", itemId}) or a peer task ({kind:"assigned_from"|"blocks"|"blocked_by"|"related", sessionId, taskId}). Passing links replaces the task's links; null clears them. The screen marks a linked task with ↔ N, and its details list each link with the peer session's name and, when the peer task is visible, its title. Links are agent claims; they grant nothing.

Agent sessions read their peers' graphs with get_project_task_graph (read-only summaries without details; see session messaging).

Limitations