OpenHands / F03 openhands-features

Home and starting work

Home is the "What do you want to work on?" screen at / and /conversations. A user describes a task in the composer and, on a local backend, can first pick a workspace folder (Open Workspace, folder browser, Manage Workspaces), a workspace mode and plugins; submitting creates a conversation and opens it. A warning banner replaces a silent failure when no LLM is configured. Below the composer, home offers recommended automations, a pinned-automations grid and an activity list of enabled automations with per-item actions.

39 mapped behaviors · 34 recipes and supporting checks · source snapshot 9 October 2026
From upstream main at 8793c111. Read the maintained source.

How to get to it

Sidebar New Chat (sidebar-conversations-link), which opens /conversations; the logo does the same (see F02).
Direct URL / (unless a page is pinned as home, see F02) or /conversations.
Command menu (Control+k, Meta+k or command-menu-trigger): search "New chat", choose New chat.
Under the composer: Open Workspace (open-workspace-button) or, once confirmed, the preview bar (home-git-control-bar-preview); Plugins (open-plugin-picker).
In the Open Workspace dialog: the combobox (workspace-dropdown) and its footer + Add Workspace (add-workspaces-button) and Manage Workspaces (manage-workspaces-button, shown once any workspace or parent exists); in Add workspaces, the Favorites/Locations sidebar (folder-browser-sidebar-<name>).
Below the composer: recommended cards (recommended-automation-rail-card-<id>), pinned cards (pinned-automation-card-<id>) and rows (running-automation-row-<id>) with their kebabs; + Add (home-automations-manage).

Before you start

Start with the common launch and health checks, then follow this family’s preconditions in order. Recipes share the fixtures and state named below.

Preconditions:

F03.llm-not-configured-banner and F03.composer-blocked-without-llm need a fresh control-openhands launch --new with only control-openhands onboard --skip done (no llm preset yet). Run them first.
Everything else: baseline state with control-openhands llm preset deepseek (deepseek-flash active).
Workspace fixtures: control-openhands fixture git-repo --name qa-f03-repo and control-openhands fixture folder --name qa-f03-folder (both under <run>/workspace).
Automation fixtures (arranged through F22 import and F21 Turn on, not proof): control-openhands fixture file --name qa-f03-pong.automation.json --content '{"version":1,"kind":"automation","spec":{"name":"QA_F03 Pong","trigger":{"type":"cron","schedule":"0 0 1 1 *","timezone":"UTC"},"enabled":true,"prompt":"Reply with the single word: pong. Do not run any tools."}}' and the same with qa-f03-beta / QA_F03 Beta. Run control-openhands browser goto /automations, then for each file run control-openhands browser click 'testid=automations-add-automation', control-openhands browser click 'testid=automations-import-automation', control-openhands browser upload 'testid=automations-import-file' "$OH_VERIFY_RUN/evidence/_fixtures/qa-f03-pong.automation.json", control-openhands browser click 'testid=import-automation-confirm', control-openhands browser wait 'testid=import-automation-modal' --state detached. Imports arrive disabled: turn each on with control-openhands browser click '[data-testid^="automation-card-"] >> has-text=QA_F03 Pong >> role=button[name="Automation actions"]' and control-openhands browser click 'role=list >> has-text=Export >> role=button[name="Turn on"]'. The yearly cron never fires by itself.
Blocked here: F03.open-repository-dialog (OpenHands Cloud backend with a connected GitHub/GitLab/Bitbucket provider), F03.isolated-workspace-notice (isolated-runtime backend), F03.workspaces-unsupported (an Agent Server without /api/workspaces), F03.recommended-prompt-launch (a Tavily/Linear/Jira integration installed so some card has nothing missing).

Behavior inventory

39 stable behavior IDs and their expected behavior

Starting work:
F03.home-entry-points /, /conversations, the sidebar New Chat and the command-menu item New chat show the launcher (home-chat-launcher) with the heading, subtitle and the Describe an engineering task… composer. Read recipe ↓
F03.llm-not-configured-banner with no usable LLM, a role=alert banner reads Your LLM isn't set up yet, so conversations won't run. Finish setup to get started.; Set up LLM opens /settings/llm; the banner is gone once a profile with a key is active. Read recipe ↓
F03.composer-blocked-without-llm with no LLM, Send is disabled and Enter creates nothing (the text stays editable). Read recipe ↓
F03.draft-persistence the home draft survives a reload and is cleared after a conversation is created. Read recipe ↓
F03.home-model-command /model <profile> sent from home activates that LLM profile without creating a conversation. Read recipe ↓
F03.launch-in-workspace submitting with a workspace picked shows Creating conversation…, opens /conversations/<id>, and the agent runs in that folder. Read recipe ↓
F03.launch-without-workspace with nothing picked, the conversation runs in a fresh per-conversation folder under the server home. Read recipe ↓
F03.create-error-toast when creation fails, the loading toast is replaced by one error toast and the prompt is not lost. Read recipe ↓
F03.plugin-picker Plugins opens Attach plugins (catalog, search, Add/Remove switch, N selected, Done and X); the pill then shows a count badge. Read recipe ↓
F03.launch-with-plugin a conversation started with a plugin attached loads it; the selection resets afterwards. Read recipe ↓
Workspaces (local backend):
F03.open-workspace-dialog Open Workspace opens a dialog with a workspace combobox; Confirm stays disabled until a pick; confirming swaps the pill for a preview bar that reopens the dialog; X and Escape close it. Read recipe ↓
F03.workspace-dropdown-search typing filters workspaces; with more than one group, workspaces are grouped by parent with an Other group; no match (or no workspaces) shows No workspaces yet. Read recipe ↓
F03.selection-after-reload after a reload the preview bar is gone, but the dialog preselects the last workspace picked in its dropdown, confirmed or not: a pick closed with the X survives leaving for another page and coming back, and a reload. Read recipe ↓
F03.workspace-mode the preview bar's mode menu switches Local Repo / New Worktree; the choice persists across reloads. Read recipe ↓
F03.folder-browser + Add Workspace opens Add workspaces at the server home with Favorites/Locations, Up and the current path; Add this directory adds and selects the folder, Add all subdirectories adds a parent whose children become workspaces, Cancel adds nothing. Read recipe ↓
F03.folder-browser-locations the browser's Favorites (Home, plus workspace once a no-folder conversation exists) and Locations (/) jump to that folder; Up is disabled at /. Read recipe ↓
F03.manage-workspaces Manage Workspaces lists workspaces and parents (with children); every Remove asks for confirmation; Cancel keeps, Confirm removes for good and clears the selection; with nothing left it reads You don't have any workspaces yet. Read recipe ↓
F03.open-repository-dialog on a Cloud backend, Open repository picks provider, repository and branch (blocked locally).
F03.isolated-workspace-notice on an isolated-runtime backend a status line explains the new isolated workspace and offers Clear host workspace (blocked locally).
F03.workspaces-unsupported on an Agent Server without workspace APIs the pill is disabled with a tooltip (blocked locally).
Automations on home:
F03.recommended-automations-rail a horizontally scrolling rail of recommended automations with edge fades; cards with a setup form open /automations/new/<id>. Read recipe ↓
F03.recommended-responder-choice GitHub/Slack responder cards on a local backend first ask Choose how your responder should run. Read recipe ↓
F03.responder-cloud-option in that dialog Open OpenHands Cloud integrations opens https://app.all-hands.dev/settings/integrations in a new tab, closes the dialog and saves no secret; X closes it without a choice. Read recipe ↓
F03.recommended-missing-integration a card whose required integration is missing opens that integration's install dialog first. Read recipe ↓
F03.recommended-hides-added a catalog automation that already exists (matched by name, enabled or not) drops off the rail; deleting it brings the card back. Read recipe ↓
F03.recommended-prompt-launch a card with no setup form and no missing integration creates a conversation that sends the automation prompt (blocked locally).
F03.home-automations-list Automations lists enabled automations with schedule, last run and status, a sparkline, + Add, and No automations yet. Add one to automate repetitive work. when empty. Read recipe ↓
F03.home-automation-links a row opens /automations/<id>, a sparkline bar opens /automations/<id>?run=<runId>, + Add opens /automations. Read recipe ↓
F03.home-run-tooltip hovering a row shows its trigger, status, last run and task. Read recipe ↓
F03.home-row-menu the row kebab offers Run now, View, Edit, Turn off and Pin to dashboard; Run now toasts Automation dispatched and is disabled while a run is in flight; Edit saves with Automation updated. Read recipe ↓
F03.cancel-in-flight-run Cancel run appears while a run is pending or running and cancels it (Automation run cancelled). Read recipe ↓
F03.turn-off-confirmation Turn off asks Turn off "<name>"? It will stop running on its schedule until you turn it back on.; Cancel keeps it on, Turn off disables it and drops it from home. Read recipe ↓
F03.pinned-automations-grid Pin to dashboard adds a card to Pinned automations (prompt, pills, status strip, Runs); the title opens the detail page; a deleted automation's card disappears. Read recipe ↓
F03.pinned-card-menu a pinned card's kebab has the same actions with Unpin from dashboard. Read recipe ↓
F03.pinned-card-links a pinned card's sparkline bar opens /automations/<id>?run=<runId>, and Enter on its focused title opens the detail page. Read recipe ↓
F03.pinned-reorder-drag dragging a pinned card's title row (Reorder <name>) onto another card reorders the pins, and the order survives a reload. Read recipe ↓
F03.home-automations-view-more past 10 rows View more/View all, past 6 pins View more/View less (not arranged).
F03.automations-backend-down with the automation service down, the rail, pinned grid and list are hidden and the composer still works. Read recipe ↓
F03.phone at 390 px the banner, launcher, rail, pinned grid, list and the workspace dialogs fit without horizontal overflow, and folder names stay readable. Read recipe ↓

Readable recipes

Read each script from top to bottom. Code is copied from the map; prose gives the action, expected observation, and conditions. <id>, <run> and similar placeholders stand for values from your own run. Short forms such as browser count continue the same control-openhands invocation; they are kept as documented.

Expected observations describe the recipe’s contract. Captures below selected recipes show representative real states from this snapshot; they do not mark every mapped behavior as passed. Follow cleanup before moving to another family.

Starting work:

No-LLM banner #

F03.llm-not-configured-banner

Note
On a fresh run after onboard --skip, run
Check
control-openhands browser text 'testid=home-llm-not-configured-banner'
Note
: Your LLM isn't set up yet, so conversations won't run. Finish setup to get started. and Set up LLM;
Do
control-openhands browser screenshot --feature F03.llm-not-configured-banner --name banner
Note
At phone width (control-openhands browser viewport phone),
Check
control-openhands browser bbox 'testid=home-llm-not-configured-banner'
is inside the viewport (F03.phone; the banner exists only before llm preset); return with
Do
control-openhands browser viewport desktop
Check
control-openhands browser click 'testid=home-llm-not-configured-action' --expect-url '/settings/llm'
Note
lands on /settings/llm.
Note
Run the blocked-composer bullet and the draft bullet next (they also need no LLM); only then
Arrange
control-openhands llm preset deepseek
Do
control-openhands browser goto /
Check
control-openhands browser count 'testid=home-llm-not-configured-banner'
is 0.

A fresh backend needs a model profile before a chat can run. CLI capture · 1440 × 1000 · 9 October 2026 · Canvas 8793c111

The home page shows the composer, Open Workspace and recommended automation cards, with a banner asking for an LLM profile.

Representative documentation capture, not a complete run of this recipe or family. Captured on an isolated local backend at desktop viewport using the current main checkout.

How this screenshot was taken

canvas: 1.26.0 · agent server: 1.53.0 · sdk: 1.53.0 · automation: 1.19.0

OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser goto /
OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser wait testid=home-screen
OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser screenshot --feature F03.llm-not-configured-banner --name home-without-profile

Blocked composer #

F03.composer-blocked-without-llm

Note
Still without an LLM, run
Do
control-openhands browser goto /
(the banner's action left /settings/llm),
Do
control-openhands browser type 'testid=chat-input' 'QA no llm'
Check
control-openhands browser enabled 'testid=home-chat-launcher >> testid=submit-button'
(false),
Do
control-openhands browser press Enter --selector 'testid=chat-input'
Check
control-openhands browser url
(still /) and
Check
control-openhands api GET '/api/conversations/search?limit=5'
(items is empty).

Draft #

F03.draft-persistence

Note
With text in the home composer,
Do
control-openhands browser reload
Check
control-openhands browser text 'testid=chat-input'
returns the same text;
Do
control-openhands browser storage --session
lists oh:home-prompt-draft.
Note
That the draft clears after a successful launch is checked in the first launch (Launch without a folder).

Entry points #

F03.home-entry-points

Do
control-openhands browser goto /conversations
Check
control-openhands browser count 'testid=home-chat-launcher'
is 1 (same for /).
Note
From /settings/secrets (control-openhands browser goto /settings/secrets),
Do
control-openhands browser press Control+k
Do
control-openhands browser type 'testid=command-menu >> role=combobox' 'New chat'
Check
control-openhands browser snapshot 'testid=command-menu'
(one option New chat Start a fresh OpenHands conversation. Go [selected]),
Do
control-openhands browser press Enter
Check
control-openhands browser url
Note
: /conversations.
Note
From /settings/secrets (control-openhands browser goto /settings/secrets again),
Check
control-openhands browser click 'testid=sidebar-conversations-link' --expect-url '/conversations(\?|$)'
Note
and browser count 'testid=home-chat-launcher' is 1.

`/model` on home #

F03.home-model-command

Check
control-openhands api GET /api/profiles
shows active_profile deepseek-flash.
Do
control-openhands browser goto /
(Entry points ended on /conversations).
Expect
The draft from the earlier bullets is still in the composer: clear it with
Do
control-openhands browser fill 'testid=chat-input' ''
(typing would append).
Do
control-openhands browser type 'testid=chat-input' '/model deepseek-pro'
Do
control-openhands browser press Escape --selector 'testid=chat-input'
(closes the slash menu),
Do
control-openhands browser press Enter --selector 'testid=chat-input'
Expect
The URL stays /, chat-input is empty, the composer's model pill (browser text 'testid=chat-input-llm-profile') reads deepseek-pro, api GET /api/profiles shows active_profile deepseek-pro, and api GET '/api/conversations/search?limit=20' lists no new conversation.
Note
Restore with the same steps and /model deepseek-flash.

Launch without a folder #

F03.launch-without-workspaceF03.draft-persistence

Do
control-openhands browser goto /conversations
(no workspace is picked yet; the pill reads Open Workspace), then fill chat-input with Reply with only the word ok. and click testid=home-chat-launcher >> testid=submit-button with --expect-url '/conversations/[^/]+$'.
Wait
control-openhands conversation wait <id> --timeout 180
Note
reports workspace <run>/private/home/workspace/project/<id without dashes>.
Expect
This is the first successful launch:
Check
control-openhands browser click 'testid=sidebar-conversations-link' --expect-url '/conversations$'
shows an empty chat-input and browser storage --session no longer lists oh:home-prompt-draft.

Plugins #

F03.plugin-picker

Do
control-openhands browser goto /conversations
(a fresh page),
Do
control-openhands browser click 'testid=open-plugin-picker'
Wait
control-openhands browser wait 'testid=plugin-picker-loading' --state hidden --timeout 60000
Note
cards plugin-picker-card-<name> are listed.
Do
control-openhands browser fill 'testid=plugin-picker-search-input' weather
Note
leaves one card (control-openhands browser count '[data-testid^="plugin-picker-card-"]' is 1); zzz-none makes browser text 'testid=plugin-picker' read No plugins available. With weather again,
Do
control-openhands browser click 'testid=plugin-picker-toggle-city-weather' --hover-first 150
Note
: the footer reads 1 selected and
Check
control-openhands browser attr 'testid=plugin-picker-toggle-city-weather' aria-label
is Remove.
Do
control-openhands browser click 'testid=plugin-picker-done'
Check
control-openhands browser text 'testid=plugin-picker-count'
is 1; reopening keeps the switch checked, and testid=plugin-picker-close also closes it.
Note
On hover-swapping cards, use --hover-first 150 for subsequent Add/Remove clicks too and assert both the label and aria-checked; the shared index gotcha explains why a plain mouse click can be swallowed (including at phone width).

Plugin reaches the agent #

F03.launch-with-plugin

Note
With city-weather attached, start the no-folder launch above without its goto (a page load drops the attached plugin), then
Check
control-openhands api GET '/api/conversations/<id>/events/search?limit=20'
Note
: the system prompt contains city-weather:now (a conversation started without the plugin has none).
Note
Back on /conversations (control-openhands browser goto /conversations),
Check
control-openhands browser count 'testid=plugin-picker-count'
is 0.

Creation failure #

F03.create-error-toast

Note
Fill chat-input with QA error path, run
Do
control-openhands service stop agent-server
Note
then clear the observation window with
Check
control-openhands browser toasts --clear
Note
Start genuine temporal evidence before submitting:
Do
control-openhands browser record start --feature F03.create-error-toast --name failed-launch
Do
control-openhands browser click 'testid=home-chat-launcher >> testid=submit-button' --observe 'role=status' --observe-ms 500
Note
then immediately
Check
control-openhands browser screenshot --feature F03.create-error-toast --name toasts
(this early still may show the loading state).
Note
Keep recording and wait for the real error with
Wait
control-openhands browser wait-text 'HTTP request failed (502 Bad Gateway)' --timeout 15000
Wait
control-openhands browser wait 'role=status >> has-text=Creating conversation…' --state hidden --timeout 15000
Note
browser toasts and browser toasts --history show Creating conversation… replaced by exactly one error toast, such as HTTP request failed (502 Bad Gateway): "Bad Gateway: connect ECONNREFUSED 127.0.0.1:<port+1>" (transport detail is preserved by design, #17985).
Expect
Count every new error toast in this window; an additional toast is a failure to record, not one to discard. browser text 'testid=chat-input' still reads QA error path and browser enabled 'testid=home-chat-launcher >> testid=submit-button' is true.
Note
Stop the recording with
Do
control-openhands browser record stop
Note
inspect its loading→error transition and recovered prompt, paired with the full screenshot.
Note
Bring the stack back with
Do
control-openhands restart
Do
control-openhands browser reload
Note
the prompt remains QA error path.

Workspaces:

Folder browser #

F03.folder-browser

Do
control-openhands browser click 'testid=open-workspace-button'
Note
before any workspace is picked,
Check
control-openhands browser snapshot 'role=dialog'
shows Open Workspace, combobox "Select a workspace" and button "Confirm" [disabled] (F03.open-workspace-dialog).
Do
control-openhands browser click 'testid=workspace-dropdown'
Note
with no saved workspace,
Check
control-openhands browser text 'testid=workspace-dropdown-empty'
is No workspaces yet, above + Add Workspace (F03.workspace-dropdown-search; browser screenshot --feature F03.workspace-dropdown-search --name empty-list).
Do
control-openhands browser click 'testid=add-workspaces-button'
Check
control-openhands browser text 'testid=folder-browser-current-path'
is <run>/private/home.
Do
control-openhands browser click 'testid=folder-browser-up'
Note
twice (now <run>) and
Do
control-openhands browser click 'testid=folder-browser-entry-workspace'
Check
control-openhands browser text 'testid=folder-browser-list'
lists qa-f03-folder and qa-f03-repo as Folder (browser screenshot --feature F03.folder-browser --name workspace-dir).
Note
Then, reopening the browser each time with browser click 'testid=workspace-dropdown' and browser click 'testid=add-workspaces-button' (the Open Workspace dialog stays open behind it; the browser always restarts at <run>/private/home, so repeat Up twice and folder-browser-entry-workspace):

Alternative paths (repeat the preparation above for each):

1. Do
  control-openhands browser click 'testid=folder-browser-cancel'
2. Note
  : browser count 'testid=folder-browser-modal' is 0 and the selection is unchanged.
1. Do
  control-openhands browser click 'testid=folder-browser-add-all-subdirs'
2. Note
  : the browser closes; after browser click 'testid=workspace-dropdown' the dropdown offers qa-f03-folder and qa-f03-repo (browser snapshot 'role=dialog': option "qa-f03-folder", option "qa-f03-repo", button "Manage Workspaces").
1. Do
  control-openhands browser click 'testid=folder-browser-use'
  (Add this directory) at <run>/workspace:
2. Check
  control-openhands browser value 'testid=workspace-dropdown'
  is workspace (auto-selected).

Favorites and locations #

F03.folder-browser-locations

Note
With the browser open,
Check
control-openhands browser testids 'testid=folder-browser-sidebar'
lists folder-browser-sidebar-home, folder-browser-sidebar-/ and, after any no-folder conversation, folder-browser-sidebar-workspace.
Do
control-openhands browser click 'testid=folder-browser-sidebar-/'
Note
makes browser text 'testid=folder-browser-current-path' read / and
Check
control-openhands browser enabled 'testid=folder-browser-up'
Note
false; folder-browser-sidebar-workspace goes to <run>/private/home/workspace and folder-browser-sidebar-home back to <run>/private/home.
Note
Close with testid=folder-browser-cancel.

Open Workspace #

F03.open-workspace-dialog

Expect
The dialog is still open from the previous bullets, with workspace selected (its disabled Confirm before a pick is checked at the start of Folder browser).
Do
control-openhands browser click 'testid=workspace-dropdown'
Do
control-openhands browser click 'testid=workspace-dropdown-menu >> role=option[name="qa-f03-repo"]'
Check
control-openhands browser enabled 'testid=workspace-launch-button'
(true),
Do
control-openhands browser click 'testid=workspace-launch-button'
Expect
The dialog closes and
Check
control-openhands browser text 'testid=home-git-control-bar-preview'
is qa-f03-repo and Local Repo (browser screenshot --feature F03.open-workspace-dialog --name preview-bar).
Do
control-openhands browser click 'testid=home-git-control-bar-preview >> role=button[name*="qa-f03-repo"]'
Note
reopens the dialog with browser value 'testid=workspace-dropdown' qa-f03-repo;
Do
control-openhands browser click 'testid=close-open-workspace-dialog'
Note
closes it, and so does
Do
control-openhands browser press Escape

Open Workspace dialog with an empty Select a workspace field and disabled Confirm button.

Representative documentation capture, not a complete run of this recipe or family. Captured on an isolated local backend at desktop viewport using the current main checkout.

How this screenshot was taken

canvas: 1.26.0 · agent server: 1.53.0 · sdk: 1.53.0 · automation: 1.19.0

OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser goto /
OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser wait testid=home-screen
OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser click testid=open-workspace-button
OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser wait role=dialog
OH_VERIFY_RUN="$OH_VERIFY_RUN" control-openhands browser screenshot role=dialog --feature F03.open-workspace-dialog --name open-workspace

Launch in a folder #

F03.launch-in-workspace

Note
Open Workspace (above) left qa-f03-repo confirmed in the preview bar.
Do
control-openhands browser fill 'testid=chat-input' 'Run pwd and reply with only its output.'
Do
control-openhands browser click 'testid=home-chat-launcher >> testid=submit-button' --observe 'text=Creating conversation' --expect-url '/conversations/[^/]+$'
Note
observed shows Creating conversation… then <absent>; the returned URL holds <id>.
Wait
control-openhands conversation wait <id> --timeout 180
Note
reports workspace <run>/workspace/qa-f03-repo, and
Check
control-openhands conversation events <id> --kinds ObservationEvent,MessageEvent
shows the terminal observation and the reply <run>/workspace/qa-f03-repo.

Search, groups and empty #

F03.workspace-dropdown-search

Do
control-openhands browser goto /
(Launch in a folder left its conversation),
Do
control-openhands browser click 'testid=open-workspace-button'
Do
control-openhands browser click 'testid=workspace-dropdown'
Note
With the dropdown open,
Do
control-openhands browser fill 'testid=workspace-dropdown' repo
Check
control-openhands browser text 'testid=workspace-dropdown-menu'
is qa-f03-repo.
Note
With the parent and the standalone workspace saved, the menu text is workspace, qa-f03-folder, qa-f03-repo, Other, workspace and
Check
control-openhands browser count 'testid=workspace-group-header'
is 2 (--name grouped).
Do
control-openhands browser fill 'testid=workspace-dropdown' zzz-none
shows the empty state:
Check
control-openhands browser text 'testid=workspace-dropdown-empty'
is No workspaces yet (--name no-match) and
Check
control-openhands browser count 'testid=add-workspaces-button'
is still 1.
Note
Clear with
Do
control-openhands browser fill 'testid=workspace-dropdown' ''
Note
browser count 'testid=workspace-dropdown-empty' is 0 again.

Reload #

F03.selection-after-reload

Expect
After confirming qa-f03-repo,
Do
control-openhands browser reload
Check
control-openhands browser count 'testid=home-git-control-bar-preview'
is 0 and the pill is back.
Note
Click it;
Check
control-openhands browser value 'testid=workspace-dropdown'
is qa-f03-repo (sessionStorage oh:home-selected-workspace-path).
Expect
An unconfirmed pick persists the same way:
Do
control-openhands browser click 'testid=workspace-dropdown'
Do
control-openhands browser click 'testid=workspace-dropdown-menu >> role=option[name="qa-f03-folder"]'
(value qa-f03-folder), then
Do
control-openhands browser click 'testid=close-open-workspace-dialog'
(never Confirm or Launch): the preview count stays 0 and
Do
control-openhands browser storage --session --values
shows oh:home-selected-workspace-path ending in /workspace/qa-f03-folder.
Note
Leave and come back with
Do
control-openhands browser goto /settings
(lands on /settings/agents, browser count 'testid=home-screen' 0) and
Do
control-openhands browser goto /conversations
Note
click open-workspace-button: browser value 'testid=workspace-dropdown' is qa-f03-folder (browser screenshot --feature F03.selection-after-reload --name unconfirmed-pick-restored).
Note
Close with the X,
Do
control-openhands browser reload
Note
click the pill again: the value is still qa-f03-folder and browser enabled 'testid=workspace-launch-button' is true.
Note
Restore the state the next bullets start from with browser click 'testid=workspace-dropdown',
Do
control-openhands browser click 'testid=workspace-dropdown-menu >> role=option[name="qa-f03-repo"]'
(value qa-f03-repo, the storage value ends in /workspace/qa-f03-repo) and
Do
control-openhands browser click 'testid=workspace-launch-button'
Note
: the dialog closes and
Check
control-openhands browser text 'testid=home-git-control-bar-preview'
is qa-f03-repo and Local Repo again.

Workspace mode #

F03.workspace-mode

Note
With the preview bar showing,
Do
control-openhands browser click 'testid=workspace-mode-selector'
Check
control-openhands browser snapshot 'testid=workspace-mode-selector-menu'
(menuitemradio "Local Repo" [checked], menuitemradio "New Worktree"),
Do
control-openhands browser click 'testid=workspace-mode-selector-option-new_worktree'
Note
browser storage --values shows openhands-last-local-workspace-mode new_worktree; after browser reload and reconfirming the workspace, browser text 'testid=home-git-control-bar-preview' reads qa-f03-repo and New Worktree.
Note
Restore with testid=workspace-mode-selector-option-local_repo.

Manage #

F03.manage-workspaces

Note
With the parent and workspace saved:
Do
control-openhands browser click 'testid=workspace-dropdown'
Do
control-openhands browser click 'testid=manage-workspaces-button'
Check
control-openhands browser testids 'testid=manage-workspaces-modal'
shows manage-workspaces-row-workspace, manage-workspaces-parent-row-workspace, manage-workspaces-child-qa-f03-folder and manage-workspaces-child-qa-f03-repo.
Do
control-openhands browser click 'testid=manage-workspaces-remove-workspace'
Check
control-openhands browser text 'testid=confirmation-modal'
reads Remove "workspace" from your saved workspaces?.
Do
control-openhands browser click 'testid=confirmation-modal >> testid=cancel-button'
Note
keeps the row (browser count 'testid=manage-workspaces-row-workspace' is 1); repeat Remove and
Do
control-openhands browser click 'testid=confirmation-modal >> testid=confirm-button'
Note
: the count is 0.
Note
Removing a workspace clears the dialog's selection only when it was the selected one: with qa-f03-repo selected,
Do
control-openhands browser click 'testid=manage-workspaces-done'
Note
leaves browser value 'testid=workspace-dropdown' at qa-f03-repo.
Expect
After browser reload the dropdown lists only the two children, and
Check
control-openhands api GET /api/workspaces
shows workspaces: [] plus the parent.
Note
Cleanup proves Remove parent:
Do
control-openhands browser click 'testid=manage-workspaces-remove-parent-workspace'
reads Remove "workspace" and its 2 child workspaces?; Confirm leaves browser text 'testid=manage-workspaces-list' at You don't have any workspaces yet. and api GET /api/workspaces empty; because the selected qa-f03-repo belonged to that parent, after browser click 'testid=manage-workspaces-done' browser value 'testid=workspace-dropdown' is empty and browser enabled 'testid=workspace-launch-button' is false.

Automations on home (fixtures imported and turned on):

Recommended rail #

F03.recommended-automations-rail

Note
On / after browser reload,
Check
control-openhands browser attr 'testid=recommended-automations-rail-fade-left' data-visible
is false and ...-fade-right is true;
Do
control-openhands browser scroll 'testid=recommended-automation-rail-card-github-agents-md-maintainer'
Note
turns the left fade true (browser screenshot --feature F03.recommended-automations-rail --name scrolled-end).
Check
control-openhands browser click 'testid=recommended-automation-rail-card-custom-automation' --expect-url 'automations/new'
Note
lands on /automations/new/custom-automation (github-pr-reviewer, github-issue-to-pr and news-digest do the same).

Responder choice #

F03.recommended-responder-choice

Note
From /conversations (control-openhands browser goto /conversations; the rail click left /automations/new/...),
Do
control-openhands browser click 'testid=recommended-automation-rail-card-github-agents-md-maintainer'
Check
control-openhands browser snapshot 'testid=responder-deployment-modal'
shows Choose how your responder should run, Continue with local setup and Open OpenHands Cloud integrations (slack-channel-monitor too).
Do
control-openhands browser click 'testid=responder-deployment-continue-local'
Note
saves an OPENHANDS_URL secret and opens the GitHub MCP install dialog (browser snapshot 'role=dialog': dialog "GitHub", Personal access token);
Do
control-openhands browser click 'role=dialog >> role=button[name="Cancel"]'
Note
closes it on /conversations.
Note
Delete OPENHANDS_URL afterwards in Settings → Secrets (F14):
Do
control-openhands browser goto /settings/secrets
Do
control-openhands browser click 'testid=secret-item >> has-text=OPENHANDS_URL >> testid=delete-secret-button'
Do
control-openhands browser click 'role=dialog >> role=button[name="Confirm"]'

Cloud option #

F03.responder-cloud-option

Note
From /conversations (control-openhands browser goto /conversations),
Do
control-openhands browser click 'testid=recommended-automation-rail-card-slack-channel-monitor'
Do
control-openhands browser click 'testid=responder-deployment-open-openhands-cloud'
Note
: browser count 'testid=responder-deployment-modal' is 0,
Do
control-openhands browser tabs
lists a second page https://app.all-hands.dev/settings/integrations (it can take a second to appear: rerun tabs before concluding) (close it with control-openhands browser close-tab 1), and api GET /api/settings/secrets has no OPENHANDS_URL.
Note
Reopen the card and
Do
control-openhands browser click 'testid=responder-deployment-modal-close'
Note
: the dialog is gone and nothing else opens.

Missing integration #

F03.recommended-missing-integration

Do
control-openhands browser click 'testid=recommended-automation-rail-card-research-brief-writer'
Note
opens dialog "Tavily" (Command npx -y tavily-mcp, Tavily API key); Cancel closes it and no conversation is created.

Already added #

F03.recommended-hides-added

Check
control-openhands browser count 'testid=recommended-automation-rail-card-news-digest'
is 1.
Note
Import qa-f03-news.automation.json (same fixture recipe as Preconditions, with "name":"Daily news digest"; it stays disabled), browser goto /, browser wait 'testid=recommended-automation-rail-card-custom-automation': the news-digest count is 0.
Note
Delete it on /automations (control-openhands browser goto /automations, then the Cleanup recipe below with has-text=Daily news digest); back on / (control-openhands browser goto /) the count is 1 again.

Activity list #

F03.home-automations-listF03.home-automation-links

Wait
control-openhands browser wait '[data-testid^="running-automation-row-"]'
Check
control-openhands browser text 'testid=running-automations-list'
Note
: both fixtures with 0 0 1 1 * and No activity yet (browser screenshot --feature F03.home-automations-list --name list); no row has a sparkline link yet (the run-bar link is checked after the first run, in the next bullet).
Do
control-openhands browser click '[data-testid^="running-automation-row-"] >> has-text=QA_F03 Beta >> role=link' --expect-url '/automations/[^/?]+'
Note
opens the detail page; after
Do
control-openhands browser goto /
Check
control-openhands browser click 'testid=home-automations-manage' --expect-url '/automations$'
Note
opens the dashboard.

Row menu, Run now and Cancel #

F03.home-row-menuF03.cancel-in-flight-runF03.home-automation-links

Do
control-openhands browser goto /
(the Manage link left the dashboard), then
Do
control-openhands browser click '[data-testid^="running-automation-row-"] >> has-text=QA_F03 Pong >> [data-testid^="running-automation-menu-"]'
Check
control-openhands browser snapshot '[data-testid^="running-automation-menu-panel-"]'
Note
: Run now, View, Edit, Turn off, separator, Pin to dashboard.
Check
control-openhands browser click '[data-testid^="running-automation-run-"]' --observe 'role=status'
Note
observes Automation dispatched.
Note
Reopen the menu: Run now [disabled] and Cancel run.
Do
control-openhands browser click '[data-testid^="running-automation-cancel-"]'
Check
control-openhands browser toasts
reads Automation run cancelled;
Check
control-openhands api GET /api/automation/v1/<automation-id>/runs
(id from browser testids --filter running-automation-row) shows CANCELLED, and after browser reload the row reads Just now · Cancelled.
Note
Pong now has a run:
Do
control-openhands browser click '[data-testid^="running-automation-activity-"] >> role=link' --expect-url '/automations/[^/?]+\?run='
Note
opens it; return with
Do
control-openhands browser goto /

Tooltip #

F03.home-run-tooltip

Do
control-openhands browser tooltip '[data-testid^="running-automation-row-"] >> has-text=QA_F03 Pong'
returns QA_F03 Pong, Trigger 0 0 1 1 *, Status Cancelled, Last run Just now, Task Cancelled by user.

View and Edit #

F03.home-row-menu

Note
From the Beta row menu,
Check
control-openhands browser click '[data-testid^="running-automation-view-"]' --expect-url '/automations/[^/?]+$'
Note
opens the detail page.
Note
Back on / (control-openhands browser goto /), reopen the menu and click [data-testid^="running-automation-edit-"]: the Edit automation modal shows browser value 'label=Name' QA_F03 Beta.
Do
control-openhands browser fill 'label=Prompt' 'Reply with the single word: beta2. Do not run any tools.'
Check
control-openhands browser click 'testid=edit-automation-save' --observe 'role=status'
(Automation updated); api GET /api/automation/v1/<automation-id> shows the new prompt.
Expect
A timeout above 1800 is refused client-side with Timeout cannot exceed 1800 seconds.

Turn off #

F03.turn-off-confirmation

Note
From the Beta row menu click [data-testid^="running-automation-turn-off-"];
Check
control-openhands browser snapshot 'role=dialog'
reads Turn off "QA_F03 Beta"? It will stop running on its schedule until you turn it back on. with Cancel and Turn off.
Do
control-openhands browser click 'role=dialog >> role=button[name="Cancel"]'
Note
keeps it enabled; repeat and
Do
control-openhands browser click 'role=dialog >> role=button[name="Turn off"]'
Note
browser reload:
Check
control-openhands browser count '[data-testid^="running-automation-row-"] >> has-text=QA_F03 Beta'
is 0 and the API shows enabled: false.
Note
Turn it back on from /automations (Preconditions) for the pin checks.

Pin #

F03.pinned-automations-grid

Do
control-openhands browser goto /
(turning Beta back on left /automations); from Pong's row menu click [data-testid^="running-automation-pin-"];
Check
control-openhands browser text 'testid=pinned-automations-dashboard'
shows Pinned automations, QA_F03 Pong, the prompt, cron and the last status; browser storage --values holds the id under oh:home-pinned-automations:<backend>:-.
Note
Pin Beta too;
Do
control-openhands browser eval "[...document.querySelectorAll('[data-testid^=pinned-automation-card-]')].map(e=>e.innerText.split('\n')[0]).join(',')"
is QA_F03 Pong,QA_F03 Beta.
Do
control-openhands browser click '[data-testid^="pinned-automation-card-"] >> role=link[name="QA_F03 Pong"]' --expect-url '/automations/[^/?]+$'
Note
opens the detail page.

Pinned menu #

F03.pinned-card-menu

Do
control-openhands browser goto /
(the Pin bullet ends on Pong's detail page), then
Do
control-openhands browser click '[data-testid^="pinned-automation-card-"] >> has-text=QA_F03 Beta >> [data-testid^="pinned-automation-menu-"]'
lists Run now, View, Edit, Turn off and Unpin from dashboard. [data-testid^="pinned-automation-run-"] toasts Automation dispatched; reopen and [data-testid^="pinned-automation-cancel-"] toasts Automation run cancelled (the run is CANCELLED).
Note
Reopen and click [data-testid^="unpin-automation-"]; after browser reload only QA_F03 Pong is pinned and Beta stays in the list.

Pinned links #

F03.pinned-card-links

Note
With Pong pinned and run once,
Do
control-openhands browser click '[data-testid^="pinned-automation-card-"] >> has-text=QA_F03 Pong >> [data-testid^="pinned-automation-activity-"] >> role=link' --expect-url '/automations/[^/?]+\?run='
Note
opens the run.
Note
Back on / (control-openhands browser goto /),
Do
control-openhands browser focus '[data-testid^="pinned-automation-card-"] >> role=link[name="QA_F03 Beta"]'
Do
control-openhands browser press Enter
Wait
control-openhands browser wait-url '/automations/[^/?]+$'
Note
opens Beta's detail page (pin Beta again first if it was unpinned).

Reorder #

F03.pinned-reorder-drag

Do
control-openhands browser goto /
(Pinned links ends on Beta's detail page).
Note
With Pong and Beta pinned (order QA_F03 Pong,QA_F03 Beta, side by side at desktop), read the Beta handle and Pong card boxes with
Check
control-openhands browser bbox '[data-testid^="pinned-automation-card-"] >> has-text=QA_F03 Beta >> [data-testid^="pinned-automation-drag-"]'
Check
control-openhands browser bbox '[data-testid^="pinned-automation-card-"] >> has-text=QA_F03 Pong'
Note
then drag the handle onto the left fifth of Pong's card:
Do
control-openhands browser drag '[data-testid^="pinned-automation-card-"] >> has-text=QA_F03 Beta >> [data-testid^="pinned-automation-drag-"]' --by -522,0 --steps 20
(at 1440×1000 the handle centre is x≈1065 and Pong's card spans x 486–864).
Expect
The order eval from the Pin bullet reads QA_F03 Beta,QA_F03 Pong, oh:home-pinned-automations:<backend>:- lists Beta's id first, and the order survives browser reload.
Note
Drag Pong's handle the same way to restore.
Expect
The target form browser drag <handle> <card> [--position before] does not reorder (the drop lands before the drag-over position is committed).

Backend down #

F03.automations-backend-down

Do
control-openhands service stop automation
Do
control-openhands browser reload
Note
then browser count on testid=running-automations-list, testid=pinned-automations-dashboard and testid=recommended-automations-rail: all 0, no toast, composer usable.
Do
control-openhands restart
Note
and browser reload bring them back.

Phone and cleanup:

Phone #

F03.phone

Do
control-openhands browser viewport phone
Check
control-openhands browser bbox 'testid=pinned-automations-dashboard'
Note
and ... 'testid=running-automations-list' (358 px wide, pageHorizontalOverflow false), browser screenshot --feature F03.phone --name automations (the banner was checked at phone width in the No-LLM banner bullet).
Note
Open Workspace:
Do
control-openhands browser click 'testid=open-workspace-button'
Note
then browser bbox 'testid=open-workspace-dialog-body' is inside the viewport.
Note
Folder browser: arrange a long name first with
Arrange
control-openhands fixture folder --name qa-f03-folder-with-a-name-too-long-for-a-phone
(it lands in <run>/workspace), then
Do
control-openhands browser click 'testid=workspace-dropdown'
Do
control-openhands browser click 'testid=add-workspaces-button'
Do
control-openhands browser eval "(()=>{const b=document.querySelector('[data-testid=folder-browser-entry-workspace] span span.truncate');return b.getBoundingClientRect().width})()"
is greater than 0 (about 67).
Do
control-openhands browser click 'testid=folder-browser-up'
Note
twice (now <run>) and
Do
control-openhands browser click 'testid=folder-browser-entry-workspace'
Do
control-openhands browser eval "(()=>{const b=document.querySelector('[data-testid=folder-browser-entry-qa-f03-folder-with-a-name-too-long-for-a-phone] span span.truncate');return [b.scrollWidth>b.clientWidth,getComputedStyle(b).textOverflow]})()"
Note
: [true,"ellipsis"] (about 109 of 293 px shown).
Do
control-openhands browser screenshot --feature F03.phone --name folder-names
shows each name beside Folder under separate Name and Kind headers, the long one cut to qa-f03-folder-w….
Note
Close with
Do
control-openhands browser click 'testid=folder-browser-cancel'
Do
control-openhands browser click 'testid=close-open-workspace-dialog'
Note
then return with
Do
control-openhands browser viewport desktop

Cleanup #

F03.pinned-automations-grid

Note
Delete both fixtures on /automations (control-openhands browser goto /automations; F21: kebab role=list >> has-text=Export >> role=button[name="Delete"], then role=heading[name="Delete automation"] >> xpath=.. >> role=button[name="Delete"]).
Note
On / (control-openhands browser goto /), browser count 'testid=pinned-automations-dashboard' is 0 and browser text 'testid=running-automations-empty-hint' is No automations yet. Add one to automate repetitive work.

Gotchas and known limits

Once a workspace is confirmed, open-workspace-button is not rendered (the preview bar replaces it): a click on it waits the full 30 s. Reopen through home-git-control-bar-preview, or reload.
A pick in the workspace dropdown is stored in sessionStorage at once, before Confirm or Launch, and closing the dialog with the X keeps it: a bullet that needs the earlier workspace selected must pick it again instead of relying on the last confirmation.
control-openhands workspace open and conversation start --workspace save that folder as a standalone workspace (api GET /api/workspaces lists it under workspaces). When another family used them first on the same stack, Add all subdirectories leaves those folders out of the workspace parent and the dropdown is grouped: options read workspace, qa-f03-repo and Other, qa-f18-repo. role=option[name="qa-f03-repo"] still matches (substring), but the menu text and the workspace-group-header count 2 in the Search bullet assume F03's own fixtures only.
Folder rows navigate on a single click; there is no path field. The browser starts at the server home, <run>/private/home, two levels below <run>. After any conversation without a workspace, <run>/private/home/workspace exists: it shows as a workspace row and, after the next page load, a workspace favorite (folder-browser-sidebar-workspace), which is not <run>/workspace.
A workspace and its parent can share a name (workspace); their test ids differ only by prefix (manage-workspaces-row- vs manage-workspaces-parent-row-).
chat-input is a contenteditable div: it stays editable when the composer is "disabled"; assert the Send button and the absence of a new conversation instead.
conversation start without --stay navigates home and loses a picked workspace and plugins; drive the submit button as above.
Responder Continue with local setup writes an OPENHANDS_URL secret; delete it so F14 counts stay clean.
The rail lists about 15 cards (proven ones, then conversation launchers such as research-brief-writer); browser testids reports only the first few, so check a card with browser count 'testid=recommended-automation-rail-card-<id>'. Any automation whose name matches a card (Daily news digest) hides that card, so avoid catalog names in fixtures.
The home draft (oh:home-prompt-draft) survives the no-LLM bullets; browser type appends to it, so browser fill 'testid=chat-input' '' before typing a slash command.
Imported automations arrive disabled and home lists only enabled ones; turn them on before looking for rows. A run dispatched from home and then cancelled still leaves a QA_F03 Pong — <date> conversation in the sidebar.
With the Agent Server stopped, a reload does not render home at all; trigger the error path before reloading, then restart.
Deleting the last automation leaves its id in the pinned localStorage key (pruning skips an empty list); the grid still hides it.
Pinned cards reorder only by mouse drag; there is no keyboard or menu alternative. Drive it with browser drag <handle> --by DX,DY --steps 20; browser drag <handle> <target> reports ok but leaves the order unchanged.
VITE_HOME_AUTOMATIONS_DEMO=true (build-time) swaps the home automation sections for demo data; never verify against such a build.
When the Agent Server is stopped, background refetches can add a generic An error occurred toast (#18051). For F03.create-error-toast, retain the complete video and toast history and report any extra toast with its timing; do not waive it from the count.
The workspace combobox uses one message for an empty list and for a search with no match: both read No workspaces yet (workspace-dropdown-empty), with + Add Workspace still below it (#18037).

Source paths: src/routes/home.tsx, src/routes/index-home.tsx, src/components/features/home/, src/components/features/plugins/plugin-picker-modal.tsx, src/components/features/automations/recommended-automations-launcher.tsx, src/hooks/use-home-pinned-automations.ts, src/hooks/use-home-automation-actions.ts, src/utils/recommended-automation-rail.ts, src/components/features/automations/responder-deployment-modal.tsx.