Skip to content
ScreenCI

Agent Integration

The fastest way to add ScreenCI is to let a coding agent do it. ScreenCI publishes an agent-readable integration brief at /integrate.md. Point your agent at it and describe the flow you want, and the agent scaffolds ScreenCI, authors a video, and records it.

The brief comes in a variant per package manager, so the agent only ever sees your manager’s commands: /integrate.md (npm), /integrate-pnpm.md (pnpm), and /integrate-yarn.md (yarn). The Get Started page hands you the matching prompt for your selection.

Start with one paste

Copy the ready-made prompt from the Get Started page in the ScreenCI app, or paste this into Claude Code, Codex, Cursor, or any other coding agent:

Integrate ScreenCI by fetching https://screenci.com/integrate.md and following its steps, then add a screenci video about <feature>

Replace <feature> with whatever you want the video to show off. Add @files or a URL so the agent has context to work from, for example add a video about the onboarding flow in @src/routes/onboarding.

What the agent does

The brief walks the agent through these steps:

  1. Scaffold the project. It runs npm init screenci@latest -- --yes at the repository root. No account or setup token is needed. The --yes flag runs the command non-interactively (defaulting the project name to the repository root directory name). This installs the screenci package, scaffolds screenci.config.ts and recordings/, and installs the screenci agent skill at the repository root. If you already have a SCREENCI_SECRET from an existing account, the agent passes it as an argument instead, so recordings upload straight to your organization.
  2. Author a video for the flow you described, including narration via video.narration({...}), with setup wrapped in hide() and the demo driven with visible clicks.
  3. Verify, then preview. It runs npx screenci test until the script is green, then npx screenci preview "<video title>" to record the free live preview and hand you the preview link, so you review the video before anything renders. Every edit you make in the Editor (narration, overlays, cuts, timings) is written back into the script, ready for the agent or you to build on: live while a screenci preview --watch session is connected, and otherwise queued and applied by the next screenci sync, test, or preview. No account is needed: without a SCREENCI_SECRET it runs under a local, anonymous trial session, and signing up in the editor claims the trial and upgrades a running session automatically.
  4. Export when you want the finished videos. npx screenci export records what changed, renders, and downloads the results into ./exports/. Exporting requires an account with an active paid subscription: the anonymous trial is preview-only, and export without a SCREENCI_SECRET prints a sign-up link instead of recording.

How the agent gathers context

To write an accurate script, the agent works from whatever context you give it:

  • Referenced files. Point it at routes and components with @files so it learns the real selectors and flow from your source.
  • Live URLs. Give it a URL when the app is deployed and you do not want to hand it the source.
  • The playwright-cli skill. init installs a playwright-cli skill (alongside the ScreenCI skill, unless you opt out with --no-playwright-cli) that lets the agent open and explore a live site before authoring the script. This is the best path when you only have a URL.

If you would rather generate a first draft yourself before involving an agent, see Playwright codegen.

Connecting the project

No account or setup token is needed to record and preview: without a SCREENCI_SECRET, preview uploads under a local, anonymous trial session and prints a link where you can view and edit the live preview, and sign up to keep it. Exporting requires an account with an active paid subscription.

To connect a project to your organization directly, copy SCREENCI_SECRET from your secrets page into screenci/.env (this is also the value you set for CI runs), or pass it to init as an argument: npm init screenci@latest <SCREENCI_SECRET>. The secret is shared across your organization, so the same value connects every project.

The upload contains the raw recording, not your source code. See Overview for how recording and rendering are split.

Prefer to wire it by hand?

Everything the agent does, you can do yourself. See Manual setup & first video.