Runtime sessions vs selector namespaces

Two distinct concepts share the word "session":

• Runtime session — which browser instance you connect to.
• Selector namespace — where cached selectors are stored on disk.

They are configured independently.

Session routing

The runtime session is resolved in priority order:

Priority	Source	Example
1	--session flag	opensteer click --session abc123
2	OPENSTEER_SESSION env	OPENSTEER_SESSION=abc123
3	OPENSTEER_CLIENT_ID binding	Non-interactive routing
4	Interactive TTY binding	Default for terminal usage

Namespace

Set the namespace with --name (CLI) or the name constructor option (SDK). Selectors are stored in .opensteer/selectors/<namespace>/.

The namespace is the link between CLI and SDK. Use the same value in both to share a selector cache:

opensteer open --name my-project

const opensteer = new Opensteer({ name: 'my-project' })

Both read from and write to .opensteer/selectors/my-project/.

getNamespace() returns the resolved namespace string.

Workflow

1. Explore with CLI (opensteer open --name my-project).
2. Cache selectors — descriptions persist automatically on resolution.
3. Cache extractions — extract schemas persist alongside selectors.
4. Generate script — the SDK reads from the same namespace, replaying cached paths without LLM calls.

Session persistence

Local sessions persist until you call close. Cloud sessions have a server-managed lifecycle.