claude-workflows: Paseo plugin

A one-stop Background tasks view in Paseo for Claude Code. It shows dynamic workflows (the Workflow tool), plain subagents (Agent/Task tool) and background shells, live, the way Claude desktop shows them.

| Where in Paseo | What it shows | | --- | --- | | Agent tab → Background tasks (opens in the right sidebar) | Every task of that agent's Claude session, grouped Running / Completed. Running tasks start expanded. Workflows expand into phases → agents → an agent inspector (prompt, live tool-call feed with inputs and outputs, result). Subagents expand straight into that inspector. Shells show the command, exit status and a live output tail. Below that, Paseo sub-agents lists child agents of any provider (Claude, Codex, omp, …); tap one to open it | | Sidebar → Background tasks | The same list for every Claude session on the machine (desktop, CLI or Paseo), filtered by Running / Last 24h | | Chat stream | A Claude agent's Workflow tool call becomes an inline card: name, Workflow · N agents · 4m 12s and a dot row. Tap it to open that run in the sidebar | | Composer pill | Background · 2 running · 105.8k (or Background · 5) on Claude agents with tasks in the last 24h | | ⌘K / Ctrl+K | "Show Background tasks", "Open all background tasks" |

How it gets the data

It doesn't need hooks or any Claude config changes. The daemon-side plugin (server/collector.ts) tails Claude Code's own files read-only, and each RPC call refreshes them incrementally:

~/.claude/projects/<slug>/<session>/subagents/workflows/<runId>/journal.jsonl     agent started/result/failed
                                                            /agent-<id>.jsonl      usage, model, tool calls
                                                            /agent-<id>.meta.json  label + phase
~/.claude/projects/<any-slug>/<session>/workflows/scripts/<name>-<runId>.js        name + planned phases (regex, never eval'd)
~/.claude/projects/<any-slug>/<session>/workflows/<runId>.json                     final snapshot (written when the run ends)
~/.claude/projects/<slug>/<session>/subagents/agent-<id>.jsonl|.meta.json            plain subagents
~/.claude/projects/<slug>/<session>.jsonl                                          launches, background shells, completion notices, cwd
/tmp/claude-<uid>/<slug>/<session>/tasks/<taskId>.output                           background shell output ("[exited with code N]" at the end)

The client polls every 1 s while something is running and every 5 s otherwise. Per-agent tokens are the latest message's context size, which matches Claude desktop's figure to within about 25 tokens. These file formats are undocumented Claude Code internals (checked on 2.1.28x) and may change.

Install

Requires Paseo 0.9.1 or later. Install on the daemon host where Claude Code runs, because the plugin reads that machine's ~/.claude (or $CLAUDE_CONFIG_DIR). The host needs npm on the daemon's PATH.

paseo daemon config set pluginsEnabled true   # or Settings → Plugins → Enable plugins
paseo plugin install npm:paseo-claude-workflows
paseo plugin ls

For a remote daemon, add --host <host> before the command (for example paseo --host ssh://user@box plugin install npm:paseo-claude-workflows), or paste npm:paseo-claude-workflows into Settings → Plugins while connected to that host. Update with paseo plugin update claude-workflows.

Develop

npm install
npm run typecheck && npm test
paseo plugin install "$PWD"                  # directory install
paseo plugin reload claude-workflows         # after edits
paseo plugin logs claude-workflows
npx tsx server/cli.ts [runId]                # collector output as JSON, no Paseo needed

Limits

• Agents that are queued but not yet started aren't on disk while a run is live, so a phase that hasn't started shows as "waiting…" until its agents spawn. The final snapshot fills in exact queued and skipped states.
• A killed run with no snapshot shows as Stalled after 15 minutes without file activity.
• There's no Stop button. Stopping a workflow has to happen inside the Claude session that owns it.
• The inline card and composer pill apply to Claude agents run through Paseo. Tasks from Claude desktop or the CLI appear in the sidebar surface.
• A shell that was killed, or whose Claude session exited, never gets an exit marker. It shows as Stalled after 30 minutes without output.
• For other harnesses the plugin shows Paseo child agents only. Provider-internal subagents (for example Codex's own) appear in Paseo's built-in Subagents track; the plugin SDK doesn't expose them.