mirror of
https://github.com/screenci/screenci.git
synced 2026-09-19 08:57:46 +08:00
Olli Paloviita
93 lines
4.5 KiB
Plaintext
93 lines
4.5 KiB
Plaintext
# 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`](https://screenci.com/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:
|
|
|
|
```text
|
|
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 flow. `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. By default the upload
|
|
refreshes the video's live preview in the web editor; exporting the
|
|
finished video (`npx screenci record --export`, or the Export button in the
|
|
editor) is a separate step that spends export minutes. Exports without an
|
|
account, and exports on the free tier, include a ScreenCI watermark;
|
|
signing up (or upgrading) removes it.
|
|
|
|
Once the video exists, refinement moves to the browser: open it in the web
|
|
app and run `screenci edit` in the project, and every edit you make in the
|
|
[Editor](/docs/guides/editor) (narration, overlays, cuts, timings) is written
|
|
back into the script, ready for the agent or you to build on.
|
|
|
|
## 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](/docs/video-script-basics#generate-a-first-draft-with-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 live preview, export it, 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](/docs) 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](/docs/manual-setup).
|