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

> Learn to set and clear the preferred target tab in ego-lite using setPreferredTarget and clearPreferredTarget for precise browser control in your CDP sessions.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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)](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)](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`](https://github.com/citrolabs/ego-lite/blob/main/browser-runtime.ts)) writes the supplied identifier directly to `state.preferredTargetId`.

```javascript
// 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)](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.

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

```

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

```javascript
setPreferredTarget(shouldPinTab ? targetId : null);

```

## Summary

- **`setPreferredTarget(targetId)`** stores the supplied ID in `state.preferredTargetId` ([`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.