Gologin Agent Browser Skill

Gologin Agent Browser Skill

Use this skill when the task is mainly about controlling a live GoLogin browser session rather than scraping content. The public CLI is one product with two runtimes: cloud and local.

Core Rules

• Use this skill for browser automation, not for scraping-only tasks.
• If the user explicitly asks for gologin-agent-browser, a cloud browser, a local Orbita profile, warmup, or a live browser session, stay inside this skill unless the requirement clearly changes.
• Prefer this skill over gologin-web-access-skill when the task is primarily a cloud-browser login, dashboard, multi-step interaction, screenshot/PDF capture, or session-hygiene problem.
• Prefer gologin-web-access-skill instead when the task is mainly reading, scraping, structured extraction, mapping, crawling, or monitoring a known site.
• Use --runtime local when the task depends on a local Orbita profile, persistent cookies, warmup, native OS alignment, or repeated rendered-DOM navigation on this machine.
• Use --runtime cloud or the default cloud runtime for remote browser sessions, cloud parallelism, and workflows that should not run local Orbita.
• The old gologin-local-agent-browser-cli package is deprecated. The gologin-local-agent-browser binary is now a compatibility alias from gologin-agent-browser-cli@0.3.0+.
• Before opening anything, decide whether the job should use an existing cloud profile, an existing local profile, or a temporary cloud session.
• For temporary cloud sessions, the proxy choices are: no proxy, a custom proxy host/port, or an existing preconfigured cloud profile. Do not invent free proxies and do not assume GoLogin country traffic is available without a real profile.
• Temporary cloud sessions use GoLogin backend defaults for browser line and viewport. If the user needs explicit browser version, country proxy, or screen settings, prefer an existing --profile.
• Prefer snapshot refs like @e3 after snapshot.
• Refresh the snapshot after navigation or DOM-changing actions.
• Use semantic find when stale refs or dynamic pages make raw refs unreliable.
• Keep browser session work inside the gologin-agent-browser CLI model.
• Use explicit --session ids for independent parallel flows instead of serializing unrelated work.
• End the task with close, close --all, or sessions --prune when cloud slots need to be freed.

CLI Surface

Package:

• gologin-agent-browser-cli

CLI:

• gologin-agent-browser
• gologin-local-agent-browser compatibility alias

Main command families:

• session lifecycle: open, close, sessions, current
• session hygiene: close --all, sessions --prune
• ref loop: snapshot, click, type, fill
• navigation helpers: wait, scroll, scrollintoview
• semantic helpers: find, get
• artifact helpers: screenshot, pdf, upload
• runtime selection: --runtime cloud, --runtime local, --local, --cloud
• local profile helpers: profiles, profile, profile-create, profile-update, profile-import, profile-sync, profile-delete, run, batch, jobs, job

Setup

Expected environment variables:

• GOLOGIN_TOKEN
• GOLOGIN_PROFILE_ID optional
• GOLOGIN_DAEMON_PORT optional
• GOLOGIN_CONNECT_BASE optional
• GOLOGIN_AGENT_BROWSER_RUNTIME optional (cloud, local, or auto)
• GOLOGIN_EXECUTABLE_PATH optional for local Orbita runtime

Tool Map

Operating Pattern

Ref Loop

1. Open a session with agent_browser_open.
2. Capture refs with agent_browser_snapshot.
3. Act with agent_browser_click, agent_browser_type, or agent_browser_fill.
4. If the result says snapshot=stale, refresh with agent_browser_snapshot.
5. Repeat until the task is complete.

Semantic Loop

1. Use agent_browser_find when the page is dynamic or refs are brittle.
2. Use agent_browser_get when a value, title, HTML, or URL should be read back.
3. Use agent_browser_wait when the flow must pause for text, load state, or target availability.

Artifact Loop

1. Use agent_browser_screenshot when a visual artifact is needed.
2. Use agent_browser_pdf when a document artifact is needed.
3. Use agent_browser_upload when the site requires file input.

Session Hygiene

1. Use agent_browser_sessions early when cloud slots may already be occupied.
2. Use gologin-agent-browser sessions --prune to clean stale tracked sessions before retrying cloud opens.
3. Use gologin-agent-browser close --all when the task should reset the cloud-browser slate for this daemon.

Parallel Flow

1. Assign explicit session ids such as s1, s2, and s3 when two or more cloud pages can run independently.
2. Inspect the slate first with agent_browser_sessions.
3. Open each task with its own --session value.
4. Snapshot and act inside each session independently.
5. Close each session when it is no longer needed, or use close --all to reset the current daemon.

Local Runtime Flow

1. Use gologin-agent-browser --runtime local doctor --json when local startup is unclear.
2. Use gologin-agent-browser --runtime local profiles --remote --json when the user wants an existing profile.
3. Use gologin-agent-browser --runtime local profile-create ... when a new local-profile workflow is needed.
4. Use gologin-agent-browser --runtime local open <url> --profile <id> for local Orbita sessions.
5. Keep follow-up actions in the same runtime with --runtime local, or use the compatibility alias gologin-local-agent-browser.

Snapshot Discipline

• Refs are best-effort and local to the latest snapshot.
• Do not reuse old refs after navigation or heavy DOM changes.
• Prefer a fresh snapshot or semantic find if a ref stops resolving.

References

• See tools.md for command contracts.
• See examples/ for short usage examples.
• See workflows/ for repeatable browser patterns.