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.

Screen map Choose Project Readiness Target Branch Identities Agents Agent Config Start Progress Dashboard ESR
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 ProjectSelect a repository or return to a recent project.
2. ReadinessInspect target safety, Git, GitHub, existing config, beads, and capabilities.
3. Target BranchSelect the branch AgentShore treats as trunk for QA, cleanup, merges, and new work.
4. GitHub IdentitiesChoose token-backed GitHub logins and trusted external PR authors.
5. Agent RunnersEnable runners and assign each one a GitHub login from the pool.
6. Agent ConfigurationDrill into each runner to choose models for small, medium, and large tiers.
7. Start SessionChoose runtime-only settings: budget, policy mode, scope, seeds, and dashboard behavior.
8. Starting ProgressShow structured startup events while the app prepares and launches AgentShore.
9. DashboardOpen the live dashboard as the primary running session surface.
10. End Session ReportDrain, 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
AgentShoreDesktop
Projects 3
Setup
Sessions
Settings

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 repositoryRead-only project checks run immediately after selection.
2
Configure app-managed setupTarget branch, GitHub login, and agent choices drive project preparation later.
3
Start when readyNo 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
AgentShoreDesktop
Readiness OK
Target
Identities
Agents
Start

example-repo readiness

/Users/user/example-repo

Change project
Continue

Project facts

read-only
OK
Git repositoryBranch main, clean working tree.
OK
OK
GitHub remoteexample-user/example-repo.
OK
i
Target branchDefault branch detected; confirm target next.
next
OK
Protected targetNot the AgentShore source repository.
OK
i
Project stateConfig and beads state will be prepared after setup choices.
later
OK
Local capabilitiesGit, gh, Codex, Claude, and API key sources detected.
OK
i
Login poolGitHub 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
AgentShoreDesktop
Readiness
Target main
Identities
Agents
Start

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
mainorigin/HEAD and GitHub default branch.
selected
i
release/1.7Available remote branch; not selected for this session.
choose
+
Use another branchEnter a remote branch name and verify it exists before continuing.
optional

Branch policy

setup input
main
origin/main
target branch
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
AgentShoreDesktop
Readiness
Target
Identities 2
Agents
Start

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-botToken source: macOS Keychain. Scope: repo, issues, pull requests.
OK
OK
@claude-worker-botToken source: environment variable. Scope: repo, issues, pull requests.
OK
+
Add GitHub loginBind another account before agent assignment if needed.
optional

Trusted PR author logins

PR ownership
@wesHuman maintainer; PRs can be tracked and reviewed.
trusted
@release-botAutomation 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
AgentShoreDesktop
Readiness
Target
Identities
Agents 3
Start

Agent runners

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

Detect again
Continue
C
Codex CLIEnabled. GitHub: @example-user-bot. Small, medium, and large tiers use recommended defaults.
Configure
A
Claude CodeEnabled. GitHub: @claude-worker-bot. Small, medium, and large tiers use recommended defaults.
Configure
G
GPT API agentEnabled. GitHub: @example-user-bot. Used for planning and review fallback.
Configure
M
Gemini CLIDisabled. 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
AgentShoreDesktop
Readiness
Target
Identities
Agents Codex CLI
Start

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-minidefault
change
M
Medium tier
gpt-5.4default
change
L
Large tier
gpt-5.5default
change

Available model selection

@example-user-bot
Codex available models
Any available model
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
AgentShoreDesktop
Readiness
Target
Identities
Agents
Start

Start a supervised session

/Users/user/example-repo

Save preset
Start session

Policy mode

Learning
Audit replay

Budget

$40.00
$20
$40
Drain to ESR

Enabled agents

Codex smallCodex mediumClaude mediumGPT fallback

Session options

Seed project, then pick ready work
/Users/user/example-repo/.agentshore/seed.md
main
Standard logging
Open after first state
Apply setup before launch

Start gate

1 required
OK
Target branch selectedmain is selected for this session.
ready
OK
Enabled agent runners3 runners enabled (minimum 2).
ready
i
Distinct GitHub identities1 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
AgentShoreDesktop
Readiness
Setup OK
Starting 6/8
Dashboard

Starting AgentShore

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

Cancel startup

Startup checklist

OK
Config mergedagentshore.yaml updated from target branch, GitHub login, and agent choices.
OK
Skills installedProject skill templates are current.
OK
Beads readyProject graph is available and healthy.
OK
IPC endpoint boundTCP loopback endpoint reserved.
5
Dashboard bridge startingWaiting for WebSocket readiness.
6
First state snapshotDashboard opens next.

Event stream

07:42:11
setup.appliedConfig, target branch, skills, GitHub logins, and beads prepared.
07:42:12
session.launchingAgentShore started in agent IPC mode.
07:42:13
ipc.boundTCP loopback endpoint reserved.
07:42:14
dashboard.waitingDashboard bridge is warming up.

9. Dashboard

Destination after startup readiness
example-repo - dashboard
session.ready
F
AgentShoreDesktop
Dashboard live
Issues 37
Agents 4
Logs
ESR
current dashboard

10. End Session Report

Drain, stop, or completion destination
example-repo - End Session Report
session.esr
F
AgentShoreDesktop
Dashboard
ESR ready
Archive
Projects
current ESR