Browser Use Desktop Agent Notes

Local Dev Profiles

The app's runtime database lives under Electron userData, not under the git worktree. Do not assume the default profile when working across branches.
Use task worktree:profile:path to get this branch's isolated profile path. It resolves to .task/user-data/<current-branch> by default.
Use task worktree:up to start the app against that isolated profile.
Use task worktree:profile:clean FORCE=1 to delete this branch's isolated profile after quitting the app.
Use task db:worktree:copy FROM=default to copy sessions.db from the platform default profile into this branch profile. Pass FROM=branch:<name> to copy from another branch profile, including branch names with /. Use an absolute path, ./relative/path, ~/path, or FROM=path:<path> for explicit filesystem paths. Pass FORCE=1 if the target DB already exists.
Use task db:worktree:doctor after copying or when local task runs fail. It compares the target sessions.db schema version and schema ID against the current checkout's src/main/sessions/schema-manifest.json.
If the app was launched with AGB_USER_DATA_DIR, run task agent:run with the same AGB_USER_DATA_DIR. The local task runner reads <userData>/local-task-server.json; pointing the CLI at a different profile will miss the running app even if sessions.db is valid.
Quit the app before copying or cleaning profile files. SQLite WAL files and Electron runtime files can be open while the app is running.

DB_SCHEMA_VERSION gates migrations at runtime.
src/main/sessions/schema-manifest.json tracks the expected fresh schema ID for CI/main drift detection.
Run task db:schema:check after touching SessionDb migrations.
Run task db:schema:update only after an intentional schema change.