Desktop onboarding and session startup

# Mockups For A No-Shell AgentShore Desktop

These screens move project selection, readiness, target branch selection, GitHub identities, agent setup, runtime startup, dashboard monitoring, and the End Session Report into the desktop app. The user never needs to invoke the AgentShore CLI directly.

Readiness discovers facts Inspection gathers project state and blocks unsafe targets without presenting setup internals as a step.
Preparation is an apply phase After target branch, GitHub logins, and agent runners are known, the app prepares config, skills, and beads state.
End sessions with ESR Drain, stop, or natural completion lands on the End Session Report, not a dead-end screen.

## Screen Map

1. Choose Project Select a repository or return to a recent project.
2. Readiness Inspect target safety, Git, GitHub, existing config, beads, and capabilities.
3. Target Branch Select the branch AgentShore treats as trunk for QA, cleanup, merges, and new work.
4. GitHub Identities Choose token-backed GitHub logins and trusted external PR authors.
5. Agent Runners Enable runners and assign each one a GitHub login from the pool.
6. Agent Configuration Drill into each runner to choose models for small, medium, and large tiers.
7. Start Session Choose runtime-only settings: budget, policy mode, scope, seeds, and dashboard behavior.
8. Starting Progress Show structured startup events while the app prepares and launches AgentShore.
9. Dashboard Open the live dashboard as the primary running session surface.
10. End Session Report Drain, stop, or completion opens ESR with report, archive, logs, and restart actions.
Repair screens are side paths from Readiness, Target Branch, Identities, Agents, Start, or Progress. They return to the originating screen after the missing prerequisite is resolved.

## 1. Choose Project

First launch, no session selected
AgentShore Desktop
v0 desktop
F
AgentShore Desktop

## Choose a project

AgentShore manages one repository at a time. Recent projects stay one click away.

Create sandbox
Open repository

### Recent projects

Sorted by last session
example-repo/Users/user/example-repo
Ready
sample-project/Users/example/Development/sample-project
Known
web-service/Users/example/Development/web-service
Stopped

### What happens next

1
Inspect repository Read-only project checks run immediately after selection.
2
Configure app-managed setup Target branch, GitHub login, and agent choices drive project preparation later.
3
Start when ready No terminal commands are needed.
AgentShore source repositories are protected targets. The app blocks real sessions there unless the user chooses an explicit sandbox.

## 2. Readiness

Read-only inspection before setup choices
example-repo - readiness
project.inspect
F
AgentShore Desktop

## example-repo readiness

/Users/user/example-repo

Change project
Continue

### Project facts

read-only
OK
Git repository Branch main, clean working tree.
OK
OK
GitHub remote example-user/example-repo.
OK
i
Target branch Default branch detected; confirm target next.
next
OK
Protected target Not the AgentShore source repository.
OK
i
Project state Config and beads state will be prepared after setup choices.
later
OK
Local capabilities Git, gh, Codex, Claude, and API key sources detected.
OK
i
Login pool GitHub logins are configured after target branch selection.
later

### Next action

Continue to target branch. The app will prepare config, skills, and beads state only after branch, login, and agent choices are known.

Readiness is not a setup screen. It only establishes whether this repo can be managed safely.

## 3. Target Branch

Branch AgentShore treats as trunk
example-repo - target branch
project.branches
F
AgentShore Desktop

## Target branch

Choose the branch AgentShore treats as trunk for QA, cleanup, merge, and new work bases.

Refresh branches
Continue to logins

### Remote branches

origin synced
OK
main origin/HEAD and GitHub default branch.
selected
i
release/1.7 Available remote branch; not selected for this session.
choose
+
Use another branch Enter a remote branch name and verify it exists before continuing.
optional

### Branch policy

setup input
Target branch main
New work base origin/main
QA and cleanup target branch
Merge destination GitHub PR base: main
The desktop app records the target branch during setup. It does not advance or rewrite the branch while preparing the project.

## 4. GitHub Identities

GitHub login pool before agent assignment
example-repo - identities
project.identities
F
AgentShore Desktop

## GitHub logins

Choose GitHub accounts before assigning logins to agent runners. These are accounts, not roles.

Add GitHub login
Continue to agents

### Token-backed GitHub logins

repo verified
OK
@example-user-bot Token source: macOS Keychain. Scope: repo, issues, pull requests.
OK
OK
@claude-worker-bot Token source: environment variable. Scope: repo, issues, pull requests.
OK
+
Add GitHub login Bind another account before agent assignment if needed.
optional

### Trusted PR author logins

PR ownership
@wes Human maintainer; PRs can be tracked and reviewed.
trusted
@release-bot Automation account allowed as external PR author.
trusted
Runner assignment happens on the next screen. This screen only defines usable GitHub logins and token sources.

## 5. Agent Runners

Assign GitHub logins, then drill into runner configuration
example-repo - agents
project.agents
F
AgentShore Desktop

## Agent runners

Enable runners, assign GitHub logins, and configure tiers and models.

Detect again
Continue
C
Codex CLI Enabled. GitHub: @example-user-bot. Small, medium, and large tiers use recommended defaults.
Configure
A
Claude Code Enabled. GitHub: @claude-worker-bot. Small, medium, and large tiers use recommended defaults.
Configure
G
GPT API agent Enabled. GitHub: @example-user-bot. Used for planning and review fallback.
Configure
M
Gemini CLI Disabled. Binary not found on this machine.
Enable
Saving agent choices triggers the app-managed preparation phase: config merge, skill install/update, login binding, beads setup, and readiness refresh.

## 6. Agent Configuration Detail

Small, medium, and large model choices
example-repo - configure Codex CLI
agent.configure
F
AgentShore Desktop

## Configure Codex CLI

Select one available model for each tier. Recommended defaults are preselected but not enforced.

Back to agents
Save runner

### Tier model map

defaults selected
S
Small tier
gpt-5.4-mini default
change
M
Medium tier
gpt-5.4 default
change
L
Large tier
gpt-5.5 default
change

### Available model selection

GitHub login@example-user-bot
Model source Codex available models
Selectable models Any available model
Defaults Recommendations only
This detail screen is opened from Agent Runners. Saving returns to the runner list; it does not start a session.

## 7. Start Session

Runtime choices only
example-repo - start
session.start
F
AgentShore Desktop

## Start a supervised session

/Users/user/example-repo

Save preset
Start session

### Policy mode

Learning
Audit replay

### Budget

$40.00
Minimum$20
Current$40
Stop rule Drain to ESR

### Enabled agents

Codex small Codex medium Claude medium GPT fallback

### Session options

Startup action Seed project, then pick ready work
Seed file/Users/user/example-repo/.agentshore/seed.md
Target branch main
Scope mode Standard logging
Dashboard Open after first state
Preparation Apply setup before launch

### Start gate

1 required
OK
Target branch selected `main` is selected for this session.
ready
OK
Enabled agent runners 3 runners enabled (minimum 2).
ready
i
Distinct GitHub identities 1 assigned; assign at least 2 distinct logins across enabled runners.
blocked
The Start button first applies the setup choices behind the scenes, then launches the AgentShore session.
Seed file appears only when startup action is set to Seed project.

## 8. Starting Progress

Structured events instead of process text
example-repo - starting
session.events
F
AgentShore Desktop

## Starting AgentShore

Applying setup choices, launching the session, and preparing the dashboard.

Cancel startup

### Startup checklist

OK
Config merged agentshore.yaml updated from target branch, GitHub login, and agent choices.
OK
Skills installed Project skill templates are current.
OK
Beads ready Project graph is available and healthy.
OK
IPC endpoint bound TCP loopback endpoint reserved.
5
Dashboard bridge starting Waiting for WebSocket readiness.
6
First state snapshot Dashboard opens next.

### Event stream

07:42:11
setup.applied Config, target branch, skills, GitHub logins, and beads prepared.
07:42:12
session.launching AgentShore started in agent IPC mode.
07:42:13
ipc.bound TCP loopback endpoint reserved.
07:42:14
dashboard.waiting Dashboard bridge is warming up.

## 9. Dashboard

Destination after startup readiness
example-repo - dashboard
session.ready
F
AgentShore Desktop
current dashboard

## 10. End Session Report

Drain, stop, or completion destination
example-repo - End Session Report
session.esr
F
AgentShore Desktop
current ESR