Browser Sessions

Overview

A browser session in Yukkai is a saved snapshot of your browser state — cookies, authentication tokens, and browsing context — that can be restored later. This lets you pick up right where you left off without re-logging into websites or re-doing CAPTCHA challenges.

Sessions are especially useful when:

• You need to interact with a site that requires login (social media, dashboards, portals).
• A website asks for multi-factor authentication (MFA), a passkey, or a CAPTCHA that only a human can complete.
• You want Yukkai to resume an authenticated browsing task across multiple conversations.
• You're testing a web app and want to preserve a specific login state between runs.

Security note: Never paste passwords or credentials directly into chat. Log in yourself using the visible browser window, then save the session. Yukkai stores session cookies locally on your device — nothing is uploaded.

---

How it works

Yukkai's browser is built on Apple WebKit (the same engine as Safari). When you save a session, Yukkai persists the following to disk:

Component	What's preserved
Cookies	Session, persistent, and secure cookies for all visited domains
Authentication state	Login tokens and session identifiers
Browsing context	The active browser profile and its configuration

Sessions are stored locally and identified by a session name you choose. You can have multiple saved sessions — for example, one for your work account and one for a personal account.

The lifecycle of a session looks like this:

1. Open browser  →  2. Log in manually  →  3. Save session  →  4. Close browser
                                          ↓
5. Later: load session  →  6. Resume authenticated browsing

When you load a saved session, Yukkai restores the cookies into a fresh browser instance. The websites you visit will recognise you as already authenticated — no need to log in again.

---

How to use it

Opening the visible browser

To save a session, you first need to log in manually. Open the visible browser window so you can interact with it directly:

web_browse(action: "show", url: "https://example.com")

This opens a real browser window you can click, type, and log in within.

Saving a session

Once you've logged in and confirmed you're authenticated, save the session:

web_browse(action: "save_session", session_name: "my-github-account")

Give the session a descriptive name so you can identify it later.

Loading a session

To restore a previously saved session:

web_browse(action: "load_session", session_name: "my-github-account")

After loading, navigate to the site — you should already be logged in.

Listing saved sessions

To see all sessions you've saved:

web_browse(action: "list_sessions")

Deleting a session

When you no longer need a session:

web_browse(action: "delete_session", session_name: "my-github-account")

Clearing all browser data

To wipe everything — cookies, cache, and sessions from the current browser instance:

web_browse(action: "clear_data")

Inspecting cookies

You can check which cookies are currently active, optionally filtered by domain:

web_browse(action: "cookies", domain: "github.com")

---

Examples

Example 1 — Logging into a portal and saving the session

1. Open the browser:
   web_browse(action: "show", url: "https://portal.example.com")

2. Log in yourself in the visible window (enter credentials, complete MFA/CAPTCHA).

3. Once authenticated, save the session:
   web_browse(action: "save_session", session_name: "portal-admin")

4. Hide the browser:
   web_browse(action: "hide")

Example 2 — Resuming an authenticated task

1. Load the saved session:
   web_browse(action: "load_session", session_name: "portal-admin")

2. Navigate to the page you need:
   web_browse(action: "navigate", url: "https://portal.example.com/dashboard")

3. Extract the content:
   web_browse(action: "extract")

Example 3 — Managing multiple accounts

# Save separate sessions for different accounts
web_browse(action: "show", url: "https://app.example.com")
# → Log in as work account → save
web_browse(action: "save_session", session_name: "work-account")

web_browse(action: "clear_data")

web_browse(action: "show", url: "https://app.example.com")
# → Log in as personal account → save
web_browse(action: "save_session", session_name: "personal-account")

# Later, switch by loading the right session
web_browse(action: "load_session", session_name: "work-account")

Example 4 — Verifying cookies persisted

# After saving and reloading a session, verify cookies are present
web_browse(action: "load_session", session_name: "my-session")
web_browse(action: "cookies", domain: "example.com")

If cookies are present, the session was saved correctly and authentication should carry over.

---

Tips

Do the login yourself

Yukkai should not enter passwords for you. Open the visible browser, log in manually, complete any CAPTCHA or MFA challenge yourself, then save the session. Yukkai takes over automation once you're authenticated.

Use clear session names

Name sessions after the site and account, e.g. github-work or stripe-dashboard. This makes it easy to find the right one when you have several saved.

Clear data between different accounts

If you're saving sessions for different accounts on the same site, run clear_data between logins to avoid cookie conflicts.

Sessions are local

All session data is stored locally on your Mac. Nothing is sent to a server. Deleting a session permanently removes its cookies from disk.

Sessions can expire

Websites may expire authentication cookies after a period of inactivity (hours, days, or weeks). If a loaded session no longer keeps you logged in, simply re-log in and save the session again.

Don't share session names with sensitive info

Avoid putting passwords or personal data in session names — they're used as identifiers and may appear in lists.

Verify after loading

After loading a session, navigate to the target site and confirm you're still authenticated before starting automation. If you've been logged out, repeat the login-and-save process.