start_recording
Start a background recording of any URL in headless Chromium, enabling you to work while it captures. Use markers and chapters to narrate, then stop to upload.
Instructions
Start a RECORDING SESSION: opens the given URL in a headless Chromium that keeps recording in the background while you continue working. Use add_marker to narrate (and optionally ASSERT on-screen state) at each step, add_chapter for before/after boundaries, then stop_recording to upload and get the share link. Set type for the recording kind, storageState/initScript to record behind a login, and exposeCdp to get a CDP endpoint you can drive with your own Playwright while it records. The session auto-stops and uploads by itself at maxSeconds (default 600) so a forgotten session can never run away. One session at a time. Requires Playwright + an ingest-scoped CLIPY_API_KEY (like the record tool). Recording the REAL Mac screen or a window's initial screen area (ScreenCaptureKit, real logged-in browser) is CLI-only — clipy session start --source mac-screen --window "<app>" — and not available via MCP. Quick per-cookie / per-localStorage-key injection (the CLI's --cookie / --local-storage) is CLI-only — use storageState here; and backdating a mark by a relative offset (the CLI's --ago) is CLI-only — use add_marker's atSeconds. The result reports the RESOLVED capture source (source: the post-redirect URL, page title and viewport actually being recorded) — compare it against the surface your driver is acting on BEFORE doing minutes of work, because Clipy will never focus or foreground a window or tab for you. This call waits for the initial navigation to settle before replying (bounded by the same 30s page-load timeout) so that reported source is measured rather than guessed — recording and the auto-stop rail both start immediately, so only the reply waits.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The http(s) URL to open and record (e.g. http://localhost:3000). | |
| name | No | Optional title for the recording. | |
| type | No | What the recording IS, so the AI summary doesn't misread it. One of: bug_report, feature_request, product_demo, walkthrough_tutorial, feedback_review, discussion_talk, other (aliases like bug/feature/demo/tutorial/review/talk accepted). | |
| width | No | Viewport + video width (default 1280). | |
| height | No | Viewport + video height (default 720). | |
| exposeCdp | No | Open a Chrome DevTools Protocol endpoint on the recording browser (default false) so you can drive the page (navigate/click/type) with your own Playwright WHILE it records. When on, the result returns cdpHttpUrl + cdpUrl and driver notes, AND the recorded page exposes window.__clipyMark(text, {assertSelector, assertText, assertUrl, failMode}) + window.__clipyChapter(label) so a CDP driver can drop asserted marks/chapters with zero extra tool calls. OFF by default (while open, any local process can attach). The env var CLIPY_DISABLE_CDP=1 is a hard kill switch that forces it off. | |
| initScript | No | Path to a JS file run in the page before every navigation (context.addInitScript). Contents are never logged. | |
| maxSeconds | No | Auto-stop ceiling in seconds (default 600, hard cap 1800). On expiry the session uploads what it captured. | |
| description | No | Optional description for the recording. | |
| userDataDir | No | Path to a Chromium user-data ROOT — the dir holding 'Local State' plus profile subdirs (macOS Chrome: ~/Library/Application Support/Google/Chrome). WITHOUT profileDirectory, Clipy opens this dir's 'Default' profile directly and writes to it, so it is refused while a live Chrome holds it locked (quit Chrome first). WITH profileDirectory, Clipy COPIES that named profile into a temporary root and records the copy — your real profile is never opened or modified. A profile SUBDIR passed as the root is refused. Mutually exclusive with storageState. | |
| storageState | No | Path to a Playwright storageState JSON (cookies + localStorage) to record behind a login. Passed unchanged to the browser context; its contents are never logged. Mutually exclusive with userDataDir. | |
| profileDirectory | No | Which profile INSIDE userDataDir to record — 'Default', 'Profile 1', 'Profile 2', … (exact folder name from chrome://version → 'Profile Path'). Clipy COPIES that profile into a temporary scratch root (as its Default) and records the copy: your real profile is never opened or modified, and the copy is deleted after upload. The result discloses the copy. Requires userDataDir. (Playwright strips Chromium's --profile-directory, so copying is the only way to select a named profile.) |