How to Set and Clear the Preferred Target Tab in ego-lite

Use setPreferredTarget(targetId) to pin a specific browser tab as the default for subsequent CDP sessions, and call clearPreferredTarget() to reset the selection logic to the most recently active tab.

ego-lite manages browser automation through Chrome DevTools Protocol (CDP) sessions that attach to specific tabs. When you need to ensure subsequent commands consistently target a particular tab—rather than whichever tab happens to be active—you can programmatically set and clear the preferred target tab in ego-lite using the runtime state API.

How the Preferred Target Mechanism Works

ego-lite maintains a single preferred tab identifier in its shared runtime state. According to the source code in [package/ego-browser/src/state.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) (line 36), the exported state object exposes a preferredTargetId field that stores either a valid targetId string or null.

When any helper needs a CDP session, it invokes ensureSession() defined in [package/ego-browser/src/browser-runtime.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) (lines 18‑23). This function checks state.preferredTargetId:

• If the ID exists and matches an open tab, ego-lite attaches the session to that specific tab.
• If the ID is null or invalid, the runtime falls back to the first active tab.

Setting a Preferred Target Tab

To designate a specific tab as the default, call setPreferredTarget(targetId). This helper function (lines 56‑62 in browser-runtime.ts) writes the supplied identifier directly to state.preferredTargetId.

// 1️⃣ Retrieve all open tabs
const tabs = await ego.listTabs();   // Returns array of tab objects

// 2️⃣ Select the tab you want to prioritize (e.g., the first one)
const targetId = tabs[0].targetId;

// 3️⃣ Pin it as the preferred target
setPreferredTarget(targetId);

// Subsequent commands (click, navigate, evaluate) now attach to this tab first

Once set, every future call to ensureSession()—invoked internally by actions like navigation in [package/ego-browser/src/driver/nav.ts](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/nav.ts`)—will attempt to attach to this tab before considering any other.

Clearing the Preferred Target Tab

To revert to standard behavior where ego-lite selects the most recently active tab, invoke clearPreferredTarget(). This function resets state.preferredTargetId to null, forcing ensureSession() to ignore any previous preference.

// Remove the preference and return to active-tab selection
clearPreferredTarget();

You can also clear the preference conditionally in a single expression:

setPreferredTarget(shouldPinTab ? targetId : null);

Summary

• setPreferredTarget(targetId) stores the supplied ID in state.preferredTargetId (src/state.ts, line 36), pinning that tab for future CDP sessions.
• clearPreferredTarget() resets the field to null, restoring the default behavior.
• ensureSession() (src/browser-runtime.ts, lines 18‑23) consults this state field when establishing sessions; if the preferred target is missing, it attaches to the first active tab.
• The preference is scoped to the current runtime state and affects helpers such as navigation, clicking, and evaluation that rely on ensureSession().

Frequently Asked Questions

What happens if the preferred target tab is closed before the next command?

If the tab referenced by state.preferredTargetId no longer exists, ensureSession() treats the preference as invalid and automatically attaches to the first active tab instead. This ensures your script continues running rather than crashing with a missing target error.

Can I set multiple preferred targets simultaneously?

No. The runtime state maintains only a single preferredTargetId field. You can only pin one tab at a time; setting a new target immediately overwrites the previous value. To alternate between tabs, you must call setPreferredTarget() with the different ID before each operation.

How does setPreferredTarget interact with existing CDP sessions?

setPreferredTarget updates the shared state but does not detach or close existing sessions. It affects only subsequent calls to ensureSession(). If you have an active session attached to a different tab, that session remains valid until explicitly closed or until the next operation triggers a new session check.

Is the preferred target persistent across separate script executions?

No. The preferredTargetId lives in the shared runtime state object held in memory. When your script terminates or the ego-lite process exits, the state is destroyed. You must call setPreferredTarget() at the start of each new execution if you need consistent targeting.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}