Skip to content
ScreenCI

AI Context

Tell the agent once, for the whole team. Coding agents make the best videos when they know where your product’s code lives, where it runs, whether they may start it, and whether it sits behind a login. The AI context page in the web app (top-right menu) stores that once for the whole organisation, so a marketer’s Add video prompt and an engineer’s Add to CI prompt start from the same facts and nobody types them into a prompt. Projects can override each field. screenci setup reads it all when an agent runs a setup prompt.

No credential is ever part of it. Signing in to your own product happens on your own machine, in a browser you drive yourself, and ScreenCI never receives what you type: see Signing In.

You will learn

The fields

Field What the agent does with it
Repository URL Reads the product’s routes, components, and README for real URLs and selectors. Clones it when the prompt runs outside the repository. Use a URL without credentials.
Site URL The address to record: a deployed site, or a localhost address for a dev server. Prefills the App URL field of every prompt dialog.
Let the agent start the app Off by default. When a localhost site does not answer, the agent stops and reports. On, the agent reads the repository, starts the dev server, and records.
This site needs a sign-in Off by default. On, the brief tells the agent to run screenci login and have you sign in before it starts authoring, instead of discovering the login page later.
Notes for the agent Free text, up to 4000 characters: how to run the app, which demo workspace to use, flows to avoid, vocabulary. Printed to the agent verbatim as “Notes from the team”.

Any member can edit the organisation values. The agent can re-read them at any time with screenci context. The look and voice new videos start from is a separate page, see Branding; the brief also lists the shared image and video assets the code can reference by name.

Project overrides

The AI context button on a project page opens the same form with an Override for this project toggle per field. A field without the toggle inherits the organisation value (shown as its placeholder). The project’s site URL override is the same value the prompt dialogs remember as the app URL.

A repository URL typed into an Add project, Add video, Edit, or Move to repository dialog is stored on that project as an override, so the field only appears while no repository is known.

The repository

When the agent runs screenci setup:

  1. If the current folder is inside a git repository whose origin is the configured repository URL (any scheme or case), that checkout is used, and its screenci/ folder (when it has a screenci.config.ts) is the workspace.
  2. Otherwise the repository is cloned shallowly into .screenci/repo next to the workspace (a .screenci/.gitignore keeps it out of the current repository). An existing clone is fast-forwarded. The clone is read-only context: the agent reads routes and components there and may start the app from it, but the workspace is ./screenci, filled from the snapshot ScreenCI holds (or scaffolded for a new project).

A clone that fails (no access from the agent’s machine) is reported in the brief; the agent continues from the site alone when the site answers. Pass --no-clone to skip cloning.

A project whose scripts ScreenCI holds no snapshot of (uploadSources: false, or nothing recorded yet) gets the Add video and Edit buttons only with a known repository URL: the agent clones or uses the repository and commits its change on a branch there.

Running the app locally

setup probes the site URL (the prompt’s App URL, else the AI context’s site URL). Any HTTP answer counts, including a login page. When nothing answers:

  • Localhost address, “Let the agent start the app” off: the brief says STOP, the JSON line carries "stop": {"reason": "site-unreachable-local"}, and the command exits with code 2. The workspace is prepared anyway; the agent reports the reason, and rerunning the same command on the same machine continues once the app is running (or the setting is on).
  • Localhost address, setting on, repository available: the brief tells the agent to read the repository’s README and package.json, start the dev server on that address, and prefer configuring it as webServer in screenci/screenci.config.ts so later runs and CI start it the same way.
  • Deployed address: STOP with site-unreachable, unless the agent passes --skip-site-check.

Sites that need a sign-in

You sign in to your own product once, in a browser ScreenCI opens for you, and every recording replays that session. The full flow is in Signing In; what matters here is the switch.

Turn This site needs a sign-in on and the brief tells the agent, before it writes anything, to:

  1. run npx screenci login,
  2. ask you to sign in in the browser that opens,
  3. run npx screenci login --done once you say you have,
  4. and then write the video with no sign-in steps in it.

Leave it off and the brief still explains the flow, but as something to reach for only if the agent runs into a login page.

Either way, the agent never asks you for a password or a code, and nothing you type reaches ScreenCI. Use a demo or test account where you can: the video shows whatever that account sees.

CI cannot open a browser, so it is handed a session instead. See CI Setup.

Site metadata

Every recording stores the origin of the first page it opened (scheme, host, and port, never the path) and whether that is a local address (localhost, *.localhost, loopback, and private network ranges) or a deployed one. Run pages show it as “Recorded against a local app at localhost:3000” or “Recorded against app.example.com”.

It also records who started the app when known: started by the recording config when webServer is set in screenci.config.ts, or started by the agent from the repository when the agent ran preview with SCREENCI_APP_LAUNCHED_BY=agent (see Configuration).

What’s next