Skip to content
ScreenCI

Start in a Repository

This is the engineer’s way in: you are already in the product’s repository with a coding agent open, and you want ScreenCI and the first video committed there from the start. 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.

Teammates who are not in the repository do not need this page: they start from the web app (Make videos by prompt), and their videos reach the repository and CI as described in Repository and CI.

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.

Have a setup code from the web app?

If someone clicked Add project, Add video, or Edit in the ScreenCI app, the prompt they sent you already carries a one-time code. Run it in the repository of the app to record (or an empty folder):

Terminal window
npx screenci@latest setup SC-XXXX-XXXX

It uses the ./screenci workspace when one exists (else pulls or creates it), writes the credentials, and prints its own brief; there is nothing else to integrate. Add --name "<project name>" to choose the new project’s name (it defaults to the folder name). See Make videos by prompt.

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 video link, so you review the video before anything renders. Every edit you make in the web editor (narration, overlays, cuts, timings) applies to the preview and later exports right away. 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.