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 record. It runs npx screenci test until the script is green, then npx screenci record to capture the final video. record uploads immediately either way: without a SCREENCI_SECRET, under a local, anonymous trial session (it prints a link to view the result and sign up to keep it); with one, straight to your organization. Renders without an account, and renders on the free tier, include a ScreenCI watermark; signing up (or upgrading) removes it.

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: without a SCREENCI_SECRET, record uploads under a local, anonymous trial session and prints a link where you can view the result and sign up to keep it.

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.