User Flow Map — Personal Workstation

Alignment Status: review · Tier: prototype · Skill: user-flow-map · Date: 2026-06-08

1. Scope & Context

Product: gblock-party personal workstation on Hetzner VPS
Goal: Replace SSH/tmux/tailscale ceremony with one-click agent management from any device
Persona: Solo developer ("The Agent Conductor") running 2–4 AI coding tools across 1–3 repos
Success condition: Agents running on remote infra, accessible from any device with zero manual SSH setup
Source evidence: positioning.md, journey-map.md, icp.md, concept-brief-personal.md

2. Technical Architecture Research

Tool Integration Patterns

Pattern	Examples	Integration Method	Notes
API-native	Claude Managed Agents SDK	REST API, server-side sessions	Cleanest integration; direct programmatic control
Headless CLI with daemon	Codex CLI (remote-control), Cursor (agent worker start)	Daemon on VPS, Unix socket/URL task submission	Built-in remote capabilities; moderate integration effort
Headless CLI (process mgmt)	Aider, Continue (cn), Cline CLI, Copilot CLI, Augment (auggie)	Process supervision, stdout capture	Multica-style stdout parsing; works with any CLI tool
IDE-dependent	Windsurf, Tabnine	Requires desktop IDE runtime	Not viable for headless VPS — out of scope

Session Persistence by Tool

Tool	Resume?	State Location	Best Integration
Claude Code CLI	Yes (`--continue`, `--resume <id>`)	`~/.claude/projects/` JSONL	Process mgmt + `--resume`
Claude Agent SDK	Yes (API-native)	Server-side	Direct REST API
Codex CLI	Yes (`codex resume <id>`)	`~/.codex/sessions/`	remote-control daemon + Unix socket
Cursor	Yes (headless worker)	Worker-managed	`agent worker start` + URL
Aider	No built-in	Git commits as checkpoints	Process mgmt
Continue (cn)	Yes (`cn --resume`)	`~/.continue/sessions/` JSON	Process mgmt + `--resume`
Cline CLI	Partial (cron persists)	Config-shared with IDE	Process mgmt + MCP
Copilot CLI	Yes (`/memory`, `/chronicle`)	GitHub-managed	Process mgmt + prompt mode

Access Mode Architecture

Mode A: Dashboard Router

Status cards, approval queue, async recap. Multica-style stdout parsing for real-time status. Low latency, mobile-friendly. Primary interface for monitoring and quick interactions.

Mode B: Terminal Drill-Down

Full xterm.js terminal via WebSocket to tmux session. Sub-100ms keystroke echo. For interactive debugging, manual commands, and deep agent interaction. Desktop-optimized.

Mode C: Code-Server IDE

VS Code in browser via code-server. Desktop-replacement experience for extended coding sessions. Full editor capabilities without local IDE. Highest resource cost.

Key: Claude Code ToS means the user's own VM with their own subscription. Agent Board is a router/connector, not a proxy. It never touches API keys or model traffic.

3. Flow Assumptions Checkpoint

Confirmed Assumptions

[from positioning] The primary user is a solo developer running AI coding agents on a Hetzner VPS
[from positioning] The competitive alternative is DIY tmux + SSH + VPS + Tailscale, not other managed tools
[from journey-map] The aha moment is "closed laptop, checked from phone, 3 PRs ready"
[from journey-map] Mobile approval routing is a core differentiator, not a nice-to-have
[user-confirmed] Personal workstation is the first product; SaaS control plane comes later
[user-confirmed] BYO-client model: users bring their own API keys and tool subscriptions
[inferred] Authentication is lightweight for personal use (single user, passkey or magic link)
[inferred] Initial tool support should cover Claude Code CLI + Codex CLI + Aider as MVP
[inferred] The dashboard is a PWA for installability on mobile and desktop
[from positioning] Zero-inbound networking (Tailscale/WireGuard tunnel) is a table-stakes security requirement

Assumptions Needing Validation

[inferred] xterm.js terminal can achieve sub-100ms latency over WireGuard to Hetzner from typical US locations
[inferred] code-server (Mode C) is worth the complexity for MVP, or should be deferred
[inferred] Multica-style stdout parsing is reliable enough for structured status extraction across tools

4. Happy Path Flow

Click each step to see its description. The flow represents the primary user journey from opening the app to shipping code.

Open PWA/CLI

→

[S1] Authenticate

→

[S3] Agent Board

→

[S4] Start Agent

→

[S3] New Card

→

[S5/S6] Interact

→

[S7] Approval

→

Close Laptop

→

[S3] Resume

→

[S8] Recap

→

[S9] Diff Review

→

Ship

5. Alternate Paths

Click each card to expand the step sequence for that alternate path.

A. First-Time Setup

▼

Install PWA / open URL — User navigates to their gblock-party instance URL for the first time
[S2] Setup Wizard — Configure VPS connection (Hetzner API key or SSH), Tailscale auth, tool API keys
Provision infrastructure — Automated setup: install tools, configure tmux, set up process supervisor
Health check — Verify connectivity, tool availability, git access
[S10] Settings confirmation — Review and save configuration
Redirect to [S3] Agent Board — Empty board with "Start your first agent" prompt

B. Phone Quick-Check

▼

Push notification — "Agent needs approval" or "3 tasks completed"
Tap notification — Opens PWA directly to relevant screen
[S1] Auto-auth — Passkey/biometric on mobile, instant
[S7] Approval card — Compact mobile-optimized view with diff summary
Approve/reject — One-tap action, agent resumes immediately
Close app — Total time: under 30 seconds

C. Parallel Sprint

▼

[S3] Agent Board — View existing running agents
[S4] Start Agent #2 — Launch second agent on different repo/branch
[S4] Start Agent #3 — Launch third agent on yet another task
[S3] Monitor all — Board shows 3+ cards, each with live status
Round-robin approvals — Handle approval requests as they arrive from different agents
[S9] Review diffs — Review completed work from each agent sequentially
Ship all — Merge PRs, handle any conflicts between agent outputs

D. Agent Recovery

▼

[S3] Agent card shows error — Red status badge, error summary visible
[S5] Click into agent — View full error output, stack trace, last successful state
Decision: retry or intervene — One-click retry with same prompt, or drop to terminal
[S6] Terminal mode — If manual intervention needed, full terminal access
Fix and restart — Resolve issue, restart agent with adjusted prompt
[S3] Agent resumes — Card transitions back to running state

E. Session Handoff (Device Switch)

▼

Working on laptop — Active terminal session with agent in Mode B
Need to leave — Close laptop lid or navigate away
Agent continues — VPS-based process is unaffected by client disconnect
Open on phone — PWA opens, auto-authenticates
[S3] Same board state — All agents show current status, no stale data
[S8] Recap available — Summary of activity since last interaction from previous device

F. Reconfigure VPS

▼

[S10] Settings — Navigate to settings from Agent Board
Update tool configuration — Add/remove tools, update API keys, change git credentials
Health check — Verify new configuration works
Optional: re-provision — If adding a new tool, run provisioning for that tool only
Return to [S3] — Agent Board reflects new capabilities

6. Decision Points

#	Decision	Who Decides	Options	Branch To
D1	First visit or returning?	System (auto-detect)	No config found → Setup Wizard; Config exists → Auth	S2 (setup) or S1 (auth)
D2	Which access mode?	User (explicit choice)	Dashboard (Mode A), Terminal (Mode B), IDE (Mode C)	S3/S5/S6 respectively
D3	Start new agent or interact with existing?	User	Start new → S4 modal; Click existing → S5/S6	S4 or S5/S6
D4	Agent requests approval	User	Approve, reject, modify prompt, defer	Agent resumes, retries, or pauses
D5	Agent encounters error	System + User	Auto-retry (transient), alert user (persistent), stop agent	Retry loop, S7 alert, or S3 error state
D6	Review completed work	User	Approve diff, request changes, discard	S9 → Ship, S9 → new agent task, or archive
D7	Device switch detected	System (auto-detect)	Show recap if time gap > threshold, else resume live	S8 recap or S3 live board
D8	Multiple agents need approval simultaneously	User	Queue (FIFO), priority sort, batch approve	S7 approval queue or batch action

7. Screen/Route Inventory

S1 — Authentication

Purpose: Verify user identity for personal workstation access
Inputs: Passkey, magic link, or biometric
Outputs: Authenticated session token
Source: [inferred] Single-user mode, lightweight auth
Access Mode: All modes (entry point)

S2 — Setup Wizard

Purpose: First-time VPS configuration and tool provisioning
Inputs: Hetzner API key, SSH credentials, Tailscale auth, tool API keys
Outputs: Provisioned VPS with tools installed and connectivity verified
Source: [from journey-map] Onboarding flow
Access Mode: Mode A (Dashboard)

S3 — Agent Board

Purpose: Central dashboard showing all agents, their status, and approval queue
Inputs: Real-time agent status via WebSocket, approval notifications
Outputs: Navigation to agent details, start agent modal, approval actions
Source: [from positioning] Unified visibility as core differentiator
Access Mode: Mode A (Dashboard) — primary interface

S4 — Start Agent Modal

Purpose: One-click agent launch with repo, tool, and prompt selection
Inputs: Repository picker, tool selector, initial prompt, optional branch
Outputs: New agent process started on VPS, card added to S3
Source: [from positioning] "One-click replaces SSH ceremony"
Access Mode: Mode A (Dashboard) — modal overlay

S5 — Agent Detail (Structured)

Purpose: Parsed, structured view of agent output and progress
Inputs: Multica-style parsed stdout, task progress, file changes
Outputs: Approval actions, prompt injection, stop/restart controls
Source: [inferred] Dashboard-native agent interaction
Access Mode: Mode A (Dashboard)

S6 — Agent Terminal

Purpose: Full interactive terminal session with the running agent
Inputs: WebSocket connection to tmux session, keyboard input
Outputs: Raw terminal output, command execution
Source: [inferred] Power-user escape hatch
Access Mode: Mode B (Terminal)

S7 — Approval Request

Purpose: Present agent's decision point for user approval/rejection
Inputs: Diff preview, agent explanation, proposed action, risk assessment
Outputs: Approve, reject, modify, or defer decision
Source: [from journey-map] Smart approval routing
Access Mode: Mode A (Dashboard) — mobile-optimized

S8 — Async Recap

Purpose: Summary of agent activity during user absence
Inputs: Time-windowed activity log, completed tasks, pending items
Outputs: Navigation to relevant agents, diffs, or approval queue
Source: [from journey-map] Device-switch continuity
Access Mode: Mode A (Dashboard)

S9 — Diff Review

Purpose: Full diff viewer for completed agent work, PR creation
Inputs: Git diff, file tree, commit history from agent session
Outputs: Approve and merge, request changes, create PR
Source: [inferred] Ship step in the flow
Access Mode: Mode A (Dashboard) or Mode C (IDE)

S10 — Settings

Purpose: Configure VPS, tools, API keys, notifications, and preferences
Inputs: Configuration values, API keys, notification preferences
Outputs: Updated configuration, re-provisioning if needed
Source: [inferred] Ongoing configuration management
Access Mode: Mode A (Dashboard)

8. Per-Screen State Matrix

S3 — Agent Board States

State	Trigger	Display
Empty	No agents configured or all stopped	Empty state with "Start your first agent" CTA and quick-start guide
All Running	All agents actively processing	Grid of green-badged cards with live stdout preview, elapsed time
Mixed Status	Some running, some idle/waiting/error	Cards sorted by status priority: error > waiting > running > idle
Approval Pending	One or more agents waiting for approval	Approval queue badge on header, waiting cards pulsate subtly
All Complete	All agents finished their tasks	Cards show completion summary, "Review diffs" CTA prominent
Connection Lost	WebSocket to VPS drops	Banner: "Reconnecting to VPS..." with auto-retry, last-known state shown

S4 — Start Agent States

State	Trigger	Display
Ready	Modal opened, repos and tools loaded	Repo picker, tool selector, prompt textarea, "Start" button enabled
Loading Repos	Modal opened, fetching repo list	Skeleton loaders in repo picker, other fields disabled
Launching	User clicked "Start"	Spinner on button, fields disabled, "Starting agent..." message
Error	Launch failed (tool not found, git error)	Error message with retry button, fields re-enabled
Tool Unavailable	Selected tool not installed on VPS	Warning with "Install tool" link to S10 settings

S5 — Agent Detail (Structured) States

State	Trigger	Display
Streaming	Agent actively producing output	Live parsed output, progress indicators, file change list updating
Waiting for Input	Agent paused for approval or user input	Approval card inline, prompt injection textarea visible
Idle	Agent finished current task, awaiting next	Completion summary, "Assign next task" CTA
Error	Agent crashed or encountered fatal error	Error details, stack trace if available, retry/restart buttons
Reconnecting	WebSocket dropped mid-stream	"Reconnecting..." overlay, buffered output replays on reconnect

S7 — Approval Request States

State	Trigger	Display
Pending	Agent requested approval, user hasn't acted	Diff preview, approve/reject buttons, timer showing wait duration
Reviewing	User expanded full diff or context	Full diff viewer, file tree, agent explanation expanded
Approved	User approved the action	Brief "Approved" confirmation, auto-return to S3 or next approval
Rejected	User rejected with optional feedback	Rejection reason textarea, agent receives feedback and adjusts
Expired	Configurable timeout elapsed without action	Grayed card, option to still approve or auto-rejected based on settings

S8 — Async Recap States

State	Trigger	Display
Activity Summary	User returns after absence (> threshold)	Timeline of events: tasks completed, approvals pending, errors, PRs created
Nothing New	User returns but agents were idle	"All quiet" message, direct to S3 Agent Board
Urgent Items	Errors or expired approvals during absence	Urgent items highlighted at top, sorted by priority
Dismissed	User closes recap	Redirect to S3, recap accessible from history menu

9. Failure & Recovery Paths

Failure	Detection	Recovery
VPS unreachable	WebSocket heartbeat timeout (>10s), health check failure	Auto-reconnect with exponential backoff. Banner notification. Agents continue running on VPS if it's a client-side issue. If VPS down, show last-known state and alert.
Agent process crash	Process supervisor detects exit code != 0	Auto-restart for transient errors (up to 3 retries). Log crash details. Notify user with error summary. Offer manual restart or terminal access.
Tailscale tunnel drop	Connectivity monitor on VPS and client	Tailscale auto-reconnect. Dashboard shows "Tunnel reconnecting..." status. Agents unaffected (running locally on VPS).
API key expiry / rate limit	Agent reports authentication or rate-limit error	Pause agent, notify user. Link to S10 settings to update key. Resume agent after key update without losing session state.
Disk space exhaustion	Monitoring daemon checks disk usage > 90%	Alert user before critical. Suggest cleanup (old sessions, build artifacts). Emergency: pause agents to prevent data corruption.
Git conflict during agent work	Agent's git operation fails with merge conflict	Agent pauses and requests approval with conflict details. User can resolve via S6 terminal or instruct agent to resolve.
Browser/PWA crash	Service worker detects unclean shutdown on next load	Agents unaffected (VPS-side). PWA reloads to S3 Agent Board with current state. No data loss.
Concurrent device conflict	Same agent interacted with from two devices simultaneously	Last-write-wins for approvals. Terminal sessions are separate tmux windows. Dashboard state is eventually consistent via WebSocket.

10. Handoffs

From	To	Mechanism	Notes
S3 Agent Board	S5/S6 Agent Detail/Terminal	Click agent card; WebSocket attaches to agent's tmux session or stdout stream	Seamless transition; agent output buffers replayed on connect
S7 Approval	Agent process (VPS)	Approval message sent via internal API to agent's stdin or control socket	Sub-second delivery; agent resumes immediately
S4 Start Agent	VPS process supervisor	REST API call to VPS backend; supervisor spawns tool process in tmux	Process isolation per agent; resource limits applied
Device A (laptop)	Device B (phone)	Shared server state; new WebSocket connection from Device B reads same state	No explicit handoff needed; state is server-canonical
S9 Diff Review	GitHub (external)	Git push from VPS; PR creation via GitHub API	Agent can auto-create PR; user reviews and merges from S9 or GitHub directly
Push notification	S7 Approval	Deep link in push notification opens PWA directly to approval card	Requires PWA service worker + push subscription; falls back to S3 if deep link fails

11. Low-Fidelity Wireframe Notes

This is a preview — not production design. Click elements to interact.

S3 — Agent Board Mockup

Interactive prototype — click an agent card to see details

Agent Board

4 agents 1 approval pending

claude-api-refactor RUNNING

Claude Code · gblock-party · 12m

Refactoring API handlers...

codex-tests WAITING

Codex · gblock-api · 34m

Approval needed: delete test fixtures

aider-docs IDLE

Aider · gblock-docs · 2h

Completed: 14 files updated

claude-migration ERROR

Claude Code · gblock-db · 8m

Git conflict in schema.sql

S4 — Start Agent Mockup

Interactive prototype — fill fields and click Start to see the launch flow

S7 — Approval Card Mockup

Interactive prototype — approve or reject to see the response

codex-tests needs approval waiting 3m

Agent wants to delete 12 test fixture files that appear unused. This is irreversible.

- tests/fixtures/old_schema.json

- tests/fixtures/legacy_data.csv

- tests/fixtures/deprecated_mock.js

... and 9 more files

12. Open Questions & Risks

Claude Code ToS compliance: Does running Claude Code CLI on a personal VPS with a personal subscription comply with Anthropic's Terms of Service? The flow assumes yes (user's own machine, own subscription), but this needs explicit verification before building the integration.
xterm.js latency budget: Can we achieve sub-100ms keystroke echo from a US-based user to a Hetzner VPS (likely in Falkenstein/Nuremberg)? If not, should Mode B (Terminal) be deprioritized for MVP in favor of structured output only?
Multica stdout parsing reliability: The Multica pattern works for Claude Code output. How well does it generalize to Codex CLI, Aider, and other tools? Each tool has different output formats. Do we need per-tool parsers?
Push notification reliability on mobile: Web Push API support varies by platform (iOS Safari limitations). Is this reliable enough for approval routing, or do we need a fallback (SMS, Telegram bot, email)?
Code-server (Mode C) ROI for MVP: code-server adds significant complexity (resource usage, VS Code extension compatibility, security surface). Should it be deferred to post-MVP, or is it essential for the "desktop replacement" positioning?
Agent resource isolation: Running 2-4 agents simultaneously on a single VPS. What are the memory/CPU requirements? Do we need cgroups/containers per agent, or is process-level isolation sufficient for a personal workstation?

13. Evidence Matrix

Claim	Source / Evidence	Inference	Confidence	Assumption Status
One-click agent start replaces SSH ceremony	`positioning.md`, `journey-map.md`	Core value prop validated across positioning frameworks	High	Validated by user
Terminal-in-browser achieves sub-100ms latency	ttyd/xterm.js research, Hetzner datacenter specs	Depends on network path; US-to-EU adds 80-120ms baseline	Medium	Needs testing
Claude Code ToS allows VM-based personal use	Anthropic API docs, ToS research	Personal subscription on personal VM should be compliant	Medium	Needs verification
Multica pattern works for stdout capture	Multica docs, GitHub source code	Proven for Claude Code; needs adaptation for other tools	High	Observed in codebase
Mobile approval routing is a core differentiator	`journey-map.md`, `positioning.md`, JTBD analysis	Rated "Unique" across multiple frameworks	High	Validated by user
PWA is sufficient for mobile (no native app needed)	PWA capability research, push notification API	PWA covers most needs; iOS Push support added in iOS 16.4+	Medium	Needs testing on target devices
2-4 agents run concurrently on a single Hetzner VPS	Hetzner pricing, agent resource profiling	CPX31 (4 vCPU, 8GB) should handle 3-4 agents; may need CPX41 for heavy use	Medium	Needs benchmarking
Zero-inbound networking via Tailscale is table stakes	`positioning.md`, category design analysis	No open ports; all traffic through encrypted tunnel	High	Validated by user

14. Confidence & Assumption Register

Conclusion	Evidence-backed?	Provisional?	What would change it?
Three-mode architecture (Dashboard/Terminal/IDE) covers all use cases	Partially — based on persona analysis, not user testing	Yes	User testing shows Mode C (IDE) is never used, or Mode B latency is unacceptable
10-screen inventory is complete for MVP	Yes — derived from flow analysis and positioning	Yes	User feedback reveals missing screens (e.g., billing, team, logs)
Process-level isolation is sufficient for personal workstation	Partially — single-user assumption reduces blast radius	Yes	Agent crash affects other agents; resource contention causes instability
Passkey auth is appropriate for personal workstation	Yes — single-user, modern auth standard	No	User has devices that don't support passkeys
Approval queue is FIFO with optional priority sorting	No — inferred from typical queue patterns	Yes	User prefers risk-based sorting, or batch approval patterns emerge
Async recap is triggered by time gap > threshold	No — inferred from device-switch pattern	Yes	User prefers always-on recap, or threshold value needs tuning
MVP tool scope: Claude Code + Codex + Aider	Partially — most common headless-viable tools	Yes	User primarily uses a different tool (e.g., Continue, Copilot)
PWA is the right client form factor	Yes — cross-device, installable, push-capable	No	Critical PWA limitation discovered (e.g., background execution on iOS)

15. Alignment Gates

Gate 1: Flow Assumptions

Are the flow assumptions and user corrections accurately captured?

Yes, accurate Needs revision Other / None of the above Need clarification

Gate 2: Architecture Decision — Access Modes

Is the three-mode architecture (Dashboard/Terminal/IDE) the right approach?

Yes, all three modes Dashboard + Terminal only (skip IDE) Dashboard only (structured data, no terminal streaming) Other / None of the above Need clarification

Gate 3: Tool Scope

Which tools should the flow map cover in the final spec?

All headless-viable tools (8 tools) Core 3 (Claude Code + Codex + Aider) Claude Code only, expand later Other / None of the above Need clarification

Gate 4: Flow Coverage

Is the flow coverage complete — screens, states, failures, handoffs?

Complete, proceed to spec Missing flows (specify in notes) Other / None of the above Need clarification

Gate 5: Artifact Destination & Proposed File Changes

Approve writing the final spec to specs/user-flow-personal-workstation.md?

Approved at proposed path Different path (specify) Other / None of the above Need clarification

Gate 6: Downstream Route

After approval, route to /ui-interview --requirements-only personal-workstation?

Yes, proceed to UI interview Different next step (specify) Other / None of the above Need clarification

Compile Review

Aggregate all section feedback and gate answers into YAML for agent consumption.