Page Context for the Assistant - Stardeck Documentation

Experimental. Page context is new and still evolving. The hook and behavior described here work today, but details may change. If anything looks off, contact us.

When someone opens your app inside Stardeck, Starcat sits in a sidebar next to it and can already see the page’s address and title. Page context lets a page hand Starcat more: a short label for what’s on screen, structured details, and instructions for how to help on this page—so the user can ask “remind this customer about their overdue invoice” without first describing what they’re looking at. This is a developer feature. You add it in your app’s code (or ask the agent to), and it only has an effect when your app runs inside the Stardeck shell. Outside the shell it does nothing, so the same code is safe to ship everywhere.

What It’s For

A few examples of context a page might declare:

An invoice detail page sets the label to Invoice #1042 (overdue) and instructs Starcat to offer drafting a payment reminder.
A customer record page shares plan: pro, MRR: $240, 14 days overdue as details, so answers reference the real numbers.
A dashboard tells Starcat which metric the user is focused on and what actions make sense from here.

Adding It

Page context is set with the useStardeckPageContext hook from @stardeck-customer-apps/client-utils (included in every app). Call it from any page or component and pass what you want Starcat to know:

import { useStardeckPageContext } from "@stardeck-customer-apps/client-utils";

function InvoicePage({ invoice }) {
  useStardeckPageContext({
    label: `Invoice #${invoice.number}${invoice.isOverdue ? " (overdue)" : ""}`,
    details: `amount: ${invoice.amountFormatted}; status: ${invoice.status}`,
    instructions:
      "This page is about a single invoice. If it's overdue, offer to draft a payment reminder email to the customer.",
    suggestedPrompts: [
      {
        label: "Draft a payment reminder",
        prompt: "Draft a friendly reminder email for this overdue invoice.",
      },
      { label: "Summarize this invoice", prompt: "Summarize this invoice and its payment status." },
    ],
  });

  return /* ...your page... */;
}

Every field is optional:

Field	What it’s for
`label`	A short, human-readable name for what’s on screen. Shown to the user in the indicator.
`details`	Structured facts about the page (amounts, status, IDs) that answers can reference.
`instructions`	Guidance on how to help on this page.
`suggestedPrompts`	Example questions shown as one-tap buttons. Each is `{ label, prompt }`—`label` is the button text, `prompt` is the message sent to the assistant.

The context updates whenever the values change and clears automatically when the user navigates away from the page or the component unmounts. Pass null to clear it yourself.

What the User Sees

Page context is visible, not hidden. Whenever a page is sharing context, an indicator appears—in the app shell header when your app is open, and in the sandbox preview toolbar while you build. The user can click it to see exactly what the page is sharing: the label, details, instructions, and any suggested prompts. Nothing is sent to the assistant that the user can’t inspect. In the app shell, the suggested prompts are one-tap buttons: tapping one opens Starcat and asks that question for the user. (In the sandbox preview they show as plain examples, since there’s no assistant attached to the preview.) Use them to point people at the most useful things to ask on each page.

How the Assistant Uses It

The context is attached to the user’s next message and given to Starcat as background on what they’re looking at. Instructions are treated as advice from your app, not as commands—Starcat considers them but won’t follow page-supplied text that conflicts with its own rules. Use them to steer toward helpful actions, not to try to override how the assistant behaves.

Common Questions

Does this work when my app runs on its own domain, outside Stardeck? The hook only has an effect inside the Stardeck shell. On a standalone deployment it’s a no-op, so you can leave the calls in place. Will old versions of my app break? No. Page context is additive. Apps that haven’t been updated simply don’t send it, and the indicator stays hidden. Can the user turn it off? The user always sees what’s being shared via the indicator and can read it in full. The page decides what to share; the platform makes it transparent. Is the page’s full text shared too? That’s a separate, user-controlled feature: the Include current page content toggle in the Starcat sidebar. Page context is what your page declares on purpose; page content is the on-screen text the user opts to share per message. See Starcat.

​What It’s For

​Adding It

​What the User Sees

​How the Assistant Uses It

​Common Questions

What It’s For

Adding It

What the User Sees

How the Assistant Uses It

Common Questions