Skip to content

workflows: add a Workflows surface to observe/manage Claude Code workflow runs #12

Description

@moonexpr

Summary

Add a Workflows surface to Claude Deck: a browser view to observe and manage
Claude Code Workflow runs — the multi-agent orchestration tool that fans out
subagents through pipeline() / parallel() stages. Today Claude Deck surfaces
Sessions, CC Bridge, Usage, etc., but workflow runs (their scripts, phase
progress, agent fan-out, and results) are invisible to the deck.

Motivation

Workflows are how non-trivial sprint/review/migration work actually executes
(localize → design → validate, fan-out candidate generation, adversarial verify).
A run can spawn dozens of agents across phases. There is currently no way to watch
a run's live progress, inspect which phase/agent is active, or review per-agent
results after the fact — the same observability gap that CC Bridge closed for
tmux sessions, but for workflow orchestration.

Proposed surface

A workflows feature module (frontend) backed by a workflows route group
(server), analogous to the existing sessions feature:

  • List view — recent/active workflow runs with run_id, script name, status,
    phase, agent count, token spend.
  • Run detail — phase tree (meta.phases), per-phase agent fan-out, live
    progress (narrator log() lines), and per-agent envelopes/results.
  • Script view — the persisted workflow script for a run (read-only), since
    every invocation persists its script under the session dir.
  • Live updates — stream run progress (SSE/websocket) the way live sessions
    already stream, so an in-flight run animates rather than requiring refresh.

Acceptance criteria

  • Backend exposes workflow runs under /api/v1/workflows (list + detail).
  • Frontend features/workflows/ module renders a list page and a run-detail
    page, registered as a route in App.tsx and the nav.
  • Run detail shows phase structure + per-agent status for at least one real
    run.
  • Live/in-flight runs update without manual refresh.
  • Source of run data is documented (where workflow run state is read from).

Repo locations

  • app/web/src/features/ — add workflows/ here (mirror sessions/,
    cc-bridge/).
  • app/web/src/App.tsx — register the route.
  • app/server/ — add a workflows route group + service (mirror the sessions
    routes).
  • Run/script artifacts: Claude Code persists each workflow script + per-agent
    agent-<id>.jsonl under the session/transcript dir — the likely data source.

Where to look first

The sessions feature end-to-end (app/web/src/features/sessions/ +
app/server/ sessions routes) is the closest existing analog — a list + paginated
detail backed by JSONL on disk. Workflows can follow the same read-from-transcript
pattern. The data source for run state is the open question to resolve first.

Context

Filed during a sprint session (repo cleanup + production reboot + docs) at the
operator's explicit request to "track workflows in Claude Deck." Discovered while
the deck itself was being rebooted to a fresh production build — workflow runs
were running in the same environment the deck manages, yet the deck has no view of
them. Labeled enhancement (repo has no priority-label scheme: bug/enhancement/…
only). Related to #1 (Rust backend rewrite) since the new surface targets the Rust
app/server/.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions