From 9debf39576e51187439ed05ebedc21d94e31fbec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Mon, 13 Apr 2026 21:41:52 +0200
Subject: [PATCH 1/4] feat: add recording quality flag

---
 .../RunnerTests+CommandExecution.swift        |  15 +-
 .../RunnerTests+Models.swift                  |   1 +
 .../RunnerTests+ScreenRecorder.swift          |  29 ++-
 .../RunnerTests.swift                         |   2 +
 .../RecordingScripts/recording-resize.swift   | 173 +++++++++++++++
 ios-runner/RUNNER_PROTOCOL.md                 |   2 +-
 .../agent-device/references/verification.md   |   1 +
 src/cli/commands/generic.ts                   |   1 +
 src/client-normalizers.ts                     |   1 +
 src/client-types.ts                           |   4 +
 src/daemon/__tests__/session-store.test.ts    |   4 +-
 .../handlers/__tests__/record-trace.test.ts   | 198 +++++++++++++++++-
 .../__tests__/session-replay-script.test.ts   |   7 +-
 src/daemon/handlers/record-trace-android.ts   |  64 +++++-
 src/daemon/handlers/record-trace-ios.ts       |   2 +
 src/daemon/handlers/record-trace-recording.ts |  32 ++-
 src/daemon/handlers/session-replay-script.ts  |   8 +
 src/daemon/script-utils.ts                    |   3 +
 src/daemon/session-store.ts                   |   1 +
 src/daemon/types.ts                           |   1 +
 .../ios/__tests__/recording-scripts.test.ts   |   8 +
 .../ios/__tests__/runner-client.test.ts       |   8 +-
 src/platforms/ios/runner-contract.ts          |   1 +
 src/recording/overlay.ts                      |  20 ++
 src/utils/__tests__/args.test.ts              |  26 ++-
 src/utils/command-schema.ts                   |  16 +-
 website/docs/docs/client-api.md               |   2 +
 website/docs/docs/commands.md                 |   2 +
 website/docs/docs/configuration.md            |   2 +-
 website/docs/docs/introduction.md             |   1 +
 30 files changed, 612 insertions(+), 23 deletions(-)
 create mode 100644 ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift

diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
index 7c85e0b0a..9c1601505 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift
@@ -183,16 +183,25 @@ extension RunnerTests {
       if let requestedFps = command.fps, (requestedFps < minRecordingFps || requestedFps > maxRecordingFps) {
         return Response(ok: false, error: ErrorPayload(message: "recordStart fps must be between \(minRecordingFps) and \(maxRecordingFps)"))
       }
+      if let requestedQuality = command.quality, (requestedQuality < minRecordingQuality || requestedQuality > maxRecordingQuality) {
+        return Response(ok: false, error: ErrorPayload(message: "recordStart quality must be between \(minRecordingQuality) and \(maxRecordingQuality)"))
+      }
       do {
         let resolvedOutPath = resolveRecordingOutPath(requestedOutPath)
         let fpsLabel = command.fps.map(String.init) ?? String(RunnerTests.defaultRecordingFps)
+        let qualityLabel = command.quality.map(String.init) ?? "native"
         NSLog(
-          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@",
+          "AGENT_DEVICE_RUNNER_RECORD_START requestedOutPath=%@ resolvedOutPath=%@ fps=%@ quality=%@",
           requestedOutPath,
           resolvedOutPath,
-          fpsLabel
+          fpsLabel,
+          qualityLabel
+        )
+        let recorder = ScreenRecorder(
+          outputPath: resolvedOutPath,
+          fps: command.fps.map { Int32($0) },
+          quality: command.quality
         )
-        let recorder = ScreenRecorder(outputPath: resolvedOutPath, fps: command.fps.map { Int32($0) })
         try recorder.start { [weak self] in
           return self?.captureRunnerFrame()
         }
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
index 08eab5168..3f8cf72f7 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift
@@ -52,6 +52,7 @@ struct Command: Codable {
   let scale: Double?
   let outPath: String?
   let fps: Int?
+  let quality: Int?
   let interactiveOnly: Bool?
   let compact: Bool?
   let depth: Int?
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
index 9c9db51f3..9d2b17971 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScreenRecorder.swift
@@ -7,6 +7,7 @@ extension RunnerTests {
   final class ScreenRecorder {
     private let outputPath: String
     private let fps: Int32?
+    private let quality: Int?
     private var effectiveFps: Int32 {
       max(1, fps ?? RunnerTests.defaultRecordingFps)
     }
@@ -25,9 +26,10 @@ extension RunnerTests {
     private var startedSession = false
     private var startError: Error?
 
-    init(outputPath: String, fps: Int32?) {
+    init(outputPath: String, fps: Int32?, quality: Int?) {
       self.outputPath = outputPath
       self.fps = fps
+      self.quality = quality
     }
 
     func start(captureFrame: @escaping () -> RunnerImage?) throws {
@@ -48,7 +50,7 @@ extension RunnerTests {
       while Date() < bootstrapDeadline {
         if let image = captureFrame(), let cgImage = runnerCGImage(from: image) {
           bootstrapImage = image
-          dimensions = CGSize(width: cgImage.width, height: cgImage.height)
+          dimensions = scaledDimensions(width: cgImage.width, height: cgImage.height)
           break
         }
         Thread.sleep(forTimeInterval: 0.05)
@@ -240,11 +242,13 @@ extension RunnerTests {
 
       CVPixelBufferLockBaseAddress(pixelBuffer, [])
       defer { CVPixelBufferUnlockBaseAddress(pixelBuffer, []) }
+      let width = CVPixelBufferGetWidth(pixelBuffer)
+      let height = CVPixelBufferGetHeight(pixelBuffer)
       guard
         let context = CGContext(
           data: CVPixelBufferGetBaseAddress(pixelBuffer),
-          width: image.width,
-          height: image.height,
+          width: width,
+          height: height,
           bitsPerComponent: 8,
           bytesPerRow: CVPixelBufferGetBytesPerRow(pixelBuffer),
           space: CGColorSpaceCreateDeviceRGB(),
@@ -253,8 +257,23 @@ extension RunnerTests {
       else {
         return nil
       }
-      context.draw(image, in: CGRect(x: 0, y: 0, width: image.width, height: image.height))
+      context.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
       return pixelBuffer
     }
+
+    private func scaledDimensions(width: Int, height: Int) -> CGSize {
+      guard let quality, quality < 10 else {
+        return CGSize(width: width, height: height)
+      }
+      let scale = Double(quality) / 10.0
+      return CGSize(
+        width: scaledEvenDimension(width, scale: scale),
+        height: scaledEvenDimension(height, scale: scale)
+      )
+    }
+
+    private func scaledEvenDimension(_ value: Int, scale: Double) -> Int {
+      max(2, Int((Double(value) * scale / 2.0).rounded()) * 2)
+    }
   }
 }
diff --git a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
index df3c983be..61a04afe3 100644
--- a/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
+++ b/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests.swift
@@ -48,6 +48,8 @@ final class RunnerTests: XCTestCase {
   let tvRemoteDoublePressDelayDefault: TimeInterval = 0.0
   let minRecordingFps = 1
   let maxRecordingFps = 120
+  let minRecordingQuality = 5
+  let maxRecordingQuality = 10
   var needsPostSnapshotInteractionDelay = false
   var needsFirstInteractionDelay = false
   var activeRecording: ScreenRecorder?
diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
new file mode 100644
index 000000000..7efe1f568
--- /dev/null
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
@@ -0,0 +1,173 @@
+import AVFoundation
+import Foundation
+
+enum ResizeError: Error, CustomStringConvertible {
+  case invalidArgs(String)
+  case missingVideoTrack
+  case exportFailed(String)
+
+  var description: String {
+    switch self {
+    case .invalidArgs(let message):
+      return message
+    case .missingVideoTrack:
+      return "Input video does not contain a video track."
+    case .exportFailed(let message):
+      return message
+    }
+  }
+}
+
+do {
+  try run()
+} catch {
+  fputs("recording-resize: \(error)\n", stderr)
+  exit(1)
+}
+
+func run() throws {
+  let arguments = Array(CommandLine.arguments.dropFirst())
+  let parsedArgs = try parseArguments(arguments)
+  let inputURL = URL(fileURLWithPath: parsedArgs.inputPath)
+  let outputURL = URL(fileURLWithPath: parsedArgs.outputPath)
+
+  if FileManager.default.fileExists(atPath: outputURL.path) {
+    try FileManager.default.removeItem(at: outputURL)
+  }
+
+  let asset = AVURLAsset(url: inputURL)
+  guard let sourceVideoTrack = asset.tracks(withMediaType: .video).first else {
+    throw ResizeError.missingVideoTrack
+  }
+
+  let renderSize = scaledRenderSize(for: sourceVideoTrack, quality: parsedArgs.quality)
+  let composition = AVMutableComposition()
+  let fullRange = CMTimeRange(start: .zero, duration: asset.duration)
+
+  guard let compositionVideoTrack = composition.addMutableTrack(
+    withMediaType: .video,
+    preferredTrackID: kCMPersistentTrackID_Invalid
+  ) else {
+    throw ResizeError.exportFailed("Failed to create composition video track.")
+  }
+  try compositionVideoTrack.insertTimeRange(fullRange, of: sourceVideoTrack, at: .zero)
+
+  if let sourceAudioTrack = asset.tracks(withMediaType: .audio).first,
+     let compositionAudioTrack = composition.addMutableTrack(
+       withMediaType: .audio,
+       preferredTrackID: kCMPersistentTrackID_Invalid
+     ) {
+    try? compositionAudioTrack.insertTimeRange(fullRange, of: sourceAudioTrack, at: .zero)
+  }
+
+  let scale = CGFloat(parsedArgs.quality) / 10.0
+  let videoComposition = AVMutableVideoComposition()
+  videoComposition.renderSize = renderSize
+  videoComposition.frameDuration = resolvedFrameDuration(for: sourceVideoTrack)
+
+  let instruction = AVMutableVideoCompositionInstruction()
+  instruction.timeRange = fullRange
+  let layerInstruction = AVMutableVideoCompositionLayerInstruction(assetTrack: compositionVideoTrack)
+  // Keep rotation/translation from the source track, then scale into the smaller render canvas.
+  let scaledTransform = sourceVideoTrack.preferredTransform.concatenating(
+    CGAffineTransform(scaleX: scale, y: scale)
+  )
+  layerInstruction.setTransform(scaledTransform, at: .zero)
+  instruction.layerInstructions = [layerInstruction]
+  videoComposition.instructions = [instruction]
+
+  guard let exporter = AVAssetExportSession(asset: composition, presetName: AVAssetExportPresetHighestQuality) else {
+    throw ResizeError.exportFailed("Failed to create export session.")
+  }
+
+  exporter.outputURL = outputURL
+  exporter.outputFileType = .mp4
+  exporter.videoComposition = videoComposition
+  exporter.shouldOptimizeForNetworkUse = true
+
+  let semaphore = DispatchSemaphore(value: 0)
+  exporter.exportAsynchronously {
+    semaphore.signal()
+  }
+  if semaphore.wait(timeout: .now() + 120) == .timedOut {
+    exporter.cancelExport()
+    throw ResizeError.exportFailed("Resize export timed out.")
+  }
+
+  if exporter.status != .completed {
+    throw ResizeError.exportFailed(exporter.error?.localizedDescription ?? "Resize export failed.")
+  }
+}
+
+func parseArguments(_ arguments: [String]) throws -> (inputPath: String, outputPath: String, quality: Int) {
+  var inputPath: String?
+  var outputPath: String?
+  var quality: Int?
+  var index = 0
+
+  while index < arguments.count {
+    let argument = arguments[index]
+    let nextIndex = index + 1
+    switch argument {
+    case "--input":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--input requires a value") }
+      inputPath = arguments[nextIndex]
+      index += 2
+    case "--output":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--output requires a value") }
+      outputPath = arguments[nextIndex]
+      index += 2
+    case "--quality":
+      guard nextIndex < arguments.count else { throw ResizeError.invalidArgs("--quality requires a value") }
+      guard let parsed = Int(arguments[nextIndex]), parsed >= 5, parsed <= 10 else {
+        throw ResizeError.invalidArgs("--quality must be an integer between 5 and 10")
+      }
+      quality = parsed
+      index += 2
+    default:
+      throw ResizeError.invalidArgs("Unknown argument: \(argument)")
+    }
+  }
+
+  guard let inputPath, let outputPath, let quality else {
+    throw ResizeError.invalidArgs(
+      "Usage: recording-resize.swift --input <video> --output <video> --quality <5-10>"
+    )
+  }
+  return (inputPath, outputPath, quality)
+}
+
+func resolvedRenderSize(for track: AVAssetTrack) -> CGSize {
+  let transformed = track.naturalSize.applying(track.preferredTransform)
+  return CGSize(width: abs(transformed.width), height: abs(transformed.height))
+}
+
+func scaledRenderSize(for track: AVAssetTrack, quality: Int) -> CGSize {
+  let renderSize = resolvedRenderSize(for: track)
+  guard quality < 10 else { return renderSize }
+  let scale = CGFloat(quality) / 10.0
+  return CGSize(
+    width: scaledDimension(renderSize.width, scale: scale),
+    height: scaledDimension(renderSize.height, scale: scale)
+  )
+}
+
+func scaledDimension(_ value: CGFloat, scale: CGFloat) -> CGFloat {
+  let evenValue = Int((Double(value * scale) / 2.0).rounded()) * 2
+  return CGFloat(max(2, evenValue))
+}
+
+func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
+  let minFrameDuration = track.minFrameDuration
+  if minFrameDuration.isValid && !minFrameDuration.isIndefinite && minFrameDuration.seconds > 0 {
+    return minFrameDuration
+  }
+
+  let nominalFrameRate = track.nominalFrameRate
+  if nominalFrameRate > 0 {
+    let timescale = Int32(max(1, round(nominalFrameRate)))
+    return CMTime(value: 1, timescale: timescale)
+  }
+
+  return CMTime(value: 1, timescale: 60)
+}
diff --git a/ios-runner/RUNNER_PROTOCOL.md b/ios-runner/RUNNER_PROTOCOL.md
index 4550d12cf..34c0a3d26 100644
--- a/ios-runner/RUNNER_PROTOCOL.md
+++ b/ios-runner/RUNNER_PROTOCOL.md
@@ -33,7 +33,7 @@ Examples:
 ```
 
 ```json
-{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30 }
+{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30, "quality": 7 }
 ```
 
 ```json
diff --git a/skills/agent-device/references/verification.md b/skills/agent-device/references/verification.md
index 40500119f..72516c317 100644
--- a/skills/agent-device/references/verification.md
+++ b/skills/agent-device/references/verification.md
@@ -82,6 +82,7 @@ agent-device record stop
 - On iOS, recording is a wrapper around `simctl` for simulators and the corresponding device capture path for physical devices.
 - On Android, recording is a wrapper around `adb`.
 - Recording writes a video artifact and a gesture-telemetry sidecar JSON.
+- Use `record start <path> --quality 5` when a smaller video is easier to inspect or share. The scale is 5-10, where 10 is native resolution; omit it to preserve native/current resolution.
 - On macOS hosts, touch overlay burn-in is available for supported recordings.
 - On non-macOS hosts, recording still succeeds but the video stays raw and `record stop` can return an `overlayWarning`.
 - If the agent already knows the interaction sequence and wants a more lifelike, uninterrupted recording, drive the flow with `batch` while recording instead of replanning between each step.
diff --git a/src/cli/commands/generic.ts b/src/cli/commands/generic.ts
index 319207780..14df6884a 100644
--- a/src/cli/commands/generic.ts
+++ b/src/cli/commands/generic.ts
@@ -205,6 +205,7 @@ export const genericClientCommandHandlers = {
         action: readStartStop(positionals[0], 'record'),
         path: positionals[1],
         fps: flags.fps,
+        quality: flags.quality as 5 | 6 | 7 | 8 | 9 | 10 | undefined,
         hideTouches: flags.hideTouches,
       }),
   ),
diff --git a/src/client-normalizers.ts b/src/client-normalizers.ts
index a1f83cbe2..a12ba53e0 100644
--- a/src/client-normalizers.ts
+++ b/src/client-normalizers.ts
@@ -274,6 +274,7 @@ export function buildFlags(options: InternalRequestOptions): CommandFlags {
     out: options.out,
     count: options.count,
     fps: options.fps,
+    quality: options.quality,
     hideTouches: options.hideTouches,
     intervalMs: options.intervalMs,
     delayMs: options.delayMs,
diff --git a/src/client-types.ts b/src/client-types.ts
index 537913f39..3c3cc0504 100644
--- a/src/client-types.ts
+++ b/src/client-types.ts
@@ -651,10 +651,13 @@ export type NetworkOptions = AgentDeviceRequestOverrides & {
   include?: 'summary' | 'headers' | 'body' | 'all';
 };
 
+type RecordingQuality = 5 | 6 | 7 | 8 | 9 | 10;
+
 export type RecordOptions = AgentDeviceRequestOverrides & {
   action: 'start' | 'stop';
   path?: string;
   fps?: number;
+  quality?: RecordingQuality;
   hideTouches?: boolean;
 };
 
@@ -716,6 +719,7 @@ type CommandExecutionOptions = {
   screenshotFullscreen?: boolean;
   count?: number;
   fps?: number;
+  quality?: RecordingQuality;
   hideTouches?: boolean;
   intervalMs?: number;
   delayMs?: number;
diff --git a/src/daemon/__tests__/session-store.test.ts b/src/daemon/__tests__/session-store.test.ts
index 1d10f6893..0c08bd411 100644
--- a/src/daemon/__tests__/session-store.test.ts
+++ b/src/daemon/__tests__/session-store.test.ts
@@ -167,7 +167,7 @@ test('writeSessionLog persists record --hide-touches flags in script output', ()
   store.recordAction(session, {
     command: 'record',
     positionals: ['start', './capture.mp4'],
-    flags: { platform: 'ios', fps: 30, hideTouches: true },
+    flags: { platform: 'ios', fps: 30, quality: 8, hideTouches: true },
     result: { action: 'start', showTouches: false },
   });
 
@@ -175,7 +175,7 @@ test('writeSessionLog persists record --hide-touches flags in script output', ()
   const scriptFile = fs.readdirSync(root).find((file) => file.endsWith('.ad'));
   assert.ok(scriptFile);
   const script = fs.readFileSync(path.join(root, scriptFile!), 'utf8');
-  assert.match(script, /record start "\.\/capture\.mp4" --fps 30 --hide-touches/);
+  assert.match(script, /record start "\.\/capture\.mp4" --fps 30 --quality 8 --hide-touches/);
 });
 
 test('writeSessionLog persists screenshot --fullscreen in script output', () => {
diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index 733781035..d07466706 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -29,6 +29,7 @@ vi.mock('../../../recording/overlay.ts', async (importOriginal) => {
   return {
     ...actual,
     trimRecordingStart: vi.fn(async () => {}),
+    resizeRecording: vi.fn(async () => {}),
     overlayRecordingTouches: vi.fn(async () => {}),
   };
 });
@@ -57,6 +58,7 @@ import {
 } from '../../../platforms/ios/runner-client.ts';
 import {
   getRecordingOverlaySupportWarning,
+  resizeRecording,
   trimRecordingStart,
   overlayRecordingTouches,
 } from '../../../recording/overlay.ts';
@@ -66,6 +68,7 @@ type RunnerCall = {
   command: string;
   outPath?: string;
   fps?: number;
+  quality?: number;
   appBundleId?: string;
   logPath?: string;
   traceLogPath?: string;
@@ -74,6 +77,7 @@ type RunnerCall = {
 const mockRunCmd = vi.mocked(runCmd);
 const mockRunCmdBackground = vi.mocked(runCmdBackground);
 const mockRunIosRunnerCommand = vi.mocked(runIosRunnerCommand);
+const mockResizeRecording = vi.mocked(resizeRecording);
 const mockTrimRecordingStart = vi.mocked(trimRecordingStart);
 const mockOverlayRecordingTouches = vi.mocked(overlayRecordingTouches);
 
@@ -128,7 +132,7 @@ async function runRecordCommand(params: {
   positionals: string[];
   logPath?: string;
   cwd?: string;
-  flags?: { fps?: number; hideTouches?: boolean };
+  flags?: { fps?: number; quality?: number; hideTouches?: boolean };
   clientArtifactPaths?: Record<string, string>;
 }) {
   return handleRecordTraceCommands({
@@ -163,6 +167,7 @@ function setupRunnerRecordingMocks(
       command: command.command,
       outPath: command.outPath,
       fps: command.fps,
+      quality: command.quality,
       appBundleId: command.appBundleId,
       logPath: options?.logPath,
       traceLogPath: options?.traceLogPath,
@@ -189,6 +194,7 @@ beforeEach(() => {
     throw new Error('runCmdBackground should not be used in this test');
   });
   mockRunIosRunnerCommand.mockImplementation(async () => ({}));
+  mockResizeRecording.mockImplementation(async () => {});
   mockTrimRecordingStart.mockImplementation(async () => {});
   mockOverlayRecordingTouches.mockImplementation(async () => {});
 });
@@ -216,6 +222,7 @@ test('record start/stop uses iOS runner on physical iOS devices', async () => {
   expect(runnerCalls[0]?.command).toBe('recordStart');
   expect(runnerCalls[0]?.outPath ?? '').toMatch(/^agent-device-recording-\d+\.mp4$/);
   expect(runnerCalls[0]?.fps).toBeUndefined();
+  expect(runnerCalls[0]?.quality).toBeUndefined();
   expect(runnerCalls[0]?.appBundleId).toBe('com.atebits.Tweetie2');
   expect(runnerCalls[0]?.logPath).toBe('/tmp/daemon.log');
   expect(runnerCalls[0]?.traceLogPath).toBeUndefined();
@@ -408,6 +415,29 @@ test('record start forwards explicit fps to iOS runner', async () => {
   expect(runCmdCalls.length).toBe(0);
 });
 
+test('record start forwards explicit quality to iOS runner', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-quality';
+  const session = makeIosDeviceSession(sessionName, 'com.atebits.Tweetie2');
+  sessionStore.set(sessionName, session);
+
+  const runnerCalls: RunnerCall[] = [];
+  const runCmdCalls: Array<{ cmd: string; args: string[] }> = [];
+  setupRunnerRecordingMocks(runnerCalls, runCmdCalls);
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './device.mp4'],
+    flags: { quality: 7 },
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(runnerCalls[0]?.command).toBe('recordStart');
+  expect(runnerCalls[0]?.quality).toBe(7);
+  expect(sessionStore.get(sessionName)?.recording?.quality).toBe(7);
+  expect(runCmdCalls.length).toBe(0);
+});
+
 test('record start rejects invalid fps value', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-invalid-fps';
@@ -434,6 +464,32 @@ test('record start rejects invalid fps value', async () => {
   );
 });
 
+test('record start rejects invalid quality value', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-device-invalid-quality';
+  sessionStore.set(sessionName, makeIosDeviceSession(sessionName));
+
+  mockRunIosRunnerCommand.mockImplementation(async () => {
+    throw new Error('runIosRunnerCommand should not be used for invalid args');
+  });
+  mockRunCmdBackground.mockImplementation(() => {
+    throw new Error('runCmdBackground should not be used for invalid args');
+  });
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './device.mp4'],
+    flags: { quality: 4 },
+  });
+
+  expect(response?.ok).toBe(false);
+  expect((response as any).error?.code).toBe('INVALID_ARGS');
+  expect((response as any).error?.message ?? '').toMatch(
+    /quality must be an integer between 5 and 10/,
+  );
+});
+
 test('record start on iOS device requires active app session context', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-device-no-app';
@@ -691,6 +747,47 @@ test('record uses simctl recordVideo for iOS simulators', async () => {
 
   expect(responseStop?.ok).toBe(true);
   expect(stopped).toBe(true);
+  expect(mockResizeRecording).not.toHaveBeenCalled();
+});
+
+test('record stop resizes iOS simulator recording when quality is explicit', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-quality';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  mockRunCmdBackground.mockImplementation(() => ({
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  }));
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim-quality.mp4'],
+    flags: { quality: 6 },
+  });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(responseStop?.ok).toBe(true);
+  expect(mockResizeRecording).toHaveBeenCalledWith({
+    videoPath: path.resolve('./sim-quality.mp4'),
+    quality: 6,
+    targetLabel: 'iOS recording',
+  });
 });
 
 test('record stop keeps iOS simulator video when overlay export fails', async () => {
@@ -857,6 +954,105 @@ test('record start/stop overlays Android gestures by default on devices', async
   }
 });
 
+test('record start passes scaled Android screenrecord size when quality is explicit', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-quality';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const adbCommands: string[] = [];
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    const command = args.join(' ');
+    adbCommands.push(command);
+    if (command === '-s emulator-5554 shell wm size') {
+      return { stdout: 'Physical size: 1080x1920\n', stderr: '', exitCode: 0 };
+    }
+    if (
+      /^-s emulator-5554 shell screenrecord --size 756x1344 \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+        command,
+      )
+    ) {
+      return { stdout: '4321\n', stderr: '', exitCode: 0 };
+    }
+    if (
+      /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(command)
+    ) {
+      return { stdout: '1024\n', stderr: '', exitCode: 0 };
+    }
+    return { stdout: '', stderr: '', exitCode: 0 };
+  });
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    flags: { quality: 7 },
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(adbCommands).toContain('-s emulator-5554 shell wm size');
+  expect(sessionStore.get(sessionName)?.recording?.quality).toBe(7);
+});
+
+test('record start scales Android screenrecord from override size when present', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-override-quality';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const adbCommands: string[] = [];
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    const command = args.join(' ');
+    adbCommands.push(command);
+    if (command === '-s emulator-5554 shell wm size') {
+      return {
+        stdout: 'Physical size: 1080x1920\nOverride size: 720x1280\n',
+        stderr: '',
+        exitCode: 0,
+      };
+    }
+    if (
+      /^-s emulator-5554 shell screenrecord --size 360x640 \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+        command,
+      )
+    ) {
+      return { stdout: '4321\n', stderr: '', exitCode: 0 };
+    }
+    if (
+      /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(command)
+    ) {
+      return { stdout: '1024\n', stderr: '', exitCode: 0 };
+    }
+    return { stdout: '', stderr: '', exitCode: 0 };
+  });
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    flags: { quality: 5 },
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(adbCommands).toContain('-s emulator-5554 shell wm size');
+});
+
 test('record stop keeps Android video when overlay export fails', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-overlay-warning';
diff --git a/src/daemon/handlers/__tests__/session-replay-script.test.ts b/src/daemon/handlers/__tests__/session-replay-script.test.ts
index 98f10bff6..733a96202 100644
--- a/src/daemon/handlers/__tests__/session-replay-script.test.ts
+++ b/src/daemon/handlers/__tests__/session-replay-script.test.ts
@@ -53,7 +53,7 @@ test('writeReplayScript preserves inline open runtime hints', () => {
   );
 });
 
-test('record replay script round-trips fps and hide-touches flags', () => {
+test('record replay script round-trips fps, quality, and hide-touches flags', () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-script-record-'));
   const replayPath = path.join(root, 'flow.ad');
   const actions: SessionAction[] = [
@@ -61,17 +61,18 @@ test('record replay script round-trips fps and hide-touches flags', () => {
       ts: Date.now(),
       command: 'record',
       positionals: ['start', './capture.mp4'],
-      flags: { fps: 24, hideTouches: true },
+      flags: { fps: 24, quality: 7, hideTouches: true },
     },
   ];
 
   writeReplayScript(replayPath, actions, makeSession());
   const script = fs.readFileSync(replayPath, 'utf8');
-  assert.match(script, /record start "\.\/capture\.mp4" --fps 24 --hide-touches/);
+  assert.match(script, /record start "\.\/capture\.mp4" --fps 24 --quality 7 --hide-touches/);
 
   const parsed = parseReplayScript(script);
   assert.deepEqual(parsed[0]?.positionals, ['start', './capture.mp4']);
   assert.equal(parsed[0]?.flags.fps, 24);
+  assert.equal(parsed[0]?.flags.quality, 7);
   assert.equal(parsed[0]?.flags.hideTouches, true);
 });
 
diff --git a/src/daemon/handlers/record-trace-android.ts b/src/daemon/handlers/record-trace-android.ts
index 1cdfac573..5589fa90a 100644
--- a/src/daemon/handlers/record-trace-android.ts
+++ b/src/daemon/handlers/record-trace-android.ts
@@ -20,7 +20,13 @@ type AndroidDevice = SessionState['device'];
 type AndroidRecording = Extract<NonNullable<SessionState['recording']>, { platform: 'android' }>;
 type AndroidRecordingBase = Pick<
   AndroidRecording,
-  'outPath' | 'clientOutPath' | 'telemetryPath' | 'startedAt' | 'showTouches' | 'gestureEvents'
+  | 'outPath'
+  | 'clientOutPath'
+  | 'telemetryPath'
+  | 'startedAt'
+  | 'quality'
+  | 'showTouches'
+  | 'gestureEvents'
 >;
 
 function parseAndroidRemotePid(stdout: string): string | undefined {
@@ -205,6 +211,50 @@ function androidRemoteRecordingPaths(timestamp: number): string[] {
   return [`/sdcard/${fileName}`, `/data/local/tmp/${fileName}`];
 }
 
+async function resolveAndroidRecordingSize(params: {
+  deps: RecordTraceDeps;
+  deviceId: string;
+  quality: number | undefined;
+}): Promise<{ width: number; height: number } | undefined> {
+  const { deps, deviceId, quality } = params;
+  if (quality === undefined || quality >= 10) {
+    return undefined;
+  }
+
+  const sizeResult = await deps.runCmd('adb', ['-s', deviceId, 'shell', 'wm', 'size'], {
+    allowFailure: true,
+  });
+  const match =
+    sizeResult.stdout.match(/Override size:\s*(\d+)x(\d+)/) ??
+    sizeResult.stdout.match(/Physical size:\s*(\d+)x(\d+)/);
+  if (sizeResult.exitCode !== 0 || !match) {
+    throw new Error(
+      `failed to resolve Android screen size for recording quality: ${formatRecordTraceExecFailure(sizeResult, 'adb shell wm size')}`,
+    );
+  }
+
+  return {
+    width: scaledEvenDimension(Number(match[1]), quality),
+    height: scaledEvenDimension(Number(match[2]), quality),
+  };
+}
+
+function scaledEvenDimension(value: number, quality: number): number {
+  return Math.max(2, Math.round((value * quality) / 10 / 2) * 2);
+}
+
+function buildAndroidScreenrecordCommand(
+  remotePath: string,
+  size: { width: number; height: number } | undefined,
+): string {
+  const screenrecordArgs = ['screenrecord'];
+  if (size) {
+    screenrecordArgs.push('--size', `${size.width}x${size.height}`);
+  }
+  screenrecordArgs.push(remotePath);
+  return `${screenrecordArgs.join(' ')} >/dev/null 2>&1 & echo $!`;
+}
+
 async function cleanupAndroidRemoteRecording(
   deps: RecordTraceDeps,
   deviceId: string,
@@ -248,11 +298,21 @@ export async function startAndroidRecording(params: {
   const { deps, device, recordingBase } = params;
   let lastStartError =
     'failed to start recording: Android screenrecord did not begin producing frames';
+  let recordingSize: { width: number; height: number } | undefined;
+  try {
+    recordingSize = await resolveAndroidRecordingSize({
+      deps,
+      deviceId: device.id,
+      quality: recordingBase.quality,
+    });
+  } catch (error) {
+    return errorResponse('COMMAND_FAILED', error instanceof Error ? error.message : String(error));
+  }
 
   for (const remotePath of androidRemoteRecordingPaths(Date.now())) {
     const startResult = await deps.runCmd(
       'adb',
-      ['-s', device.id, 'shell', `screenrecord ${remotePath} >/dev/null 2>&1 & echo $!`],
+      ['-s', device.id, 'shell', buildAndroidScreenrecordCommand(remotePath, recordingSize)],
       {
         allowFailure: true,
       },
diff --git a/src/daemon/handlers/record-trace-ios.ts b/src/daemon/handlers/record-trace-ios.ts
index cffc98cfc..efe90b4b4 100644
--- a/src/daemon/handlers/record-trace-ios.ts
+++ b/src/daemon/handlers/record-trace-ios.ts
@@ -124,6 +124,7 @@ export async function startIosDeviceRecording(params: {
         command: 'recordStart',
         outPath: recordingFileName,
         fps: fpsFlag,
+        quality: recordingBase.quality,
         appBundleId,
       },
       runnerOptions,
@@ -223,6 +224,7 @@ export async function startMacOsRecording(params: {
         command: 'recordStart',
         outPath: recordingBase.outPath,
         fps: fpsFlag,
+        quality: recordingBase.quality,
         appBundleId,
       },
       getRunnerOptions(req, logPath, activeSession),
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index ccd7a3359..0c4b53ff2 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -15,7 +15,11 @@ import { runCmd, runCmdBackground } from '../../utils/exec.ts';
 import { isPlayableVideo, waitForStableFile } from '../../utils/video.ts';
 import { deriveRecordingTelemetryPath } from '../recording-telemetry.ts';
 import { runIosRunnerCommand } from '../../platforms/ios/runner-client.ts';
-import { overlayRecordingTouches, trimRecordingStart } from '../../recording/overlay.ts';
+import {
+  overlayRecordingTouches,
+  resizeRecording,
+  trimRecordingStart,
+} from '../../recording/overlay.ts';
 import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
 import { formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import { finalizeRecordingOverlay } from './record-trace-finalize.ts';
@@ -32,6 +36,8 @@ import {
 
 const IOS_DEVICE_RECORD_MIN_FPS = 1;
 const IOS_DEVICE_RECORD_MAX_FPS = 120;
+const RECORDING_MIN_QUALITY = 5;
+const RECORDING_MAX_QUALITY = 10;
 const LOCAL_RECORDING_READY_POLL_MS = 250;
 const LOCAL_RECORDING_READY_SETTLE_POLLS = 2;
 
@@ -42,6 +48,7 @@ export type RecordTraceDeps = {
   waitForStableFile: typeof waitForStableFile;
   isPlayableVideo: typeof isPlayableVideo;
   trimRecordingStart: typeof trimRecordingStart;
+  resizeRecording: typeof resizeRecording;
   overlayRecordingTouches: typeof overlayRecordingTouches;
 };
 
@@ -49,6 +56,7 @@ export type RecordingBase = {
   outPath: string;
   clientOutPath?: string;
   startedAt: number;
+  quality?: number;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
 };
@@ -61,6 +69,7 @@ export function buildRecordTraceDeps(): RecordTraceDeps {
     waitForStableFile,
     isPlayableVideo,
     trimRecordingStart,
+    resizeRecording,
     overlayRecordingTouches,
   };
 }
@@ -70,6 +79,7 @@ function buildRecordingBase(req: DaemonRequest, outPath: string): RecordingBase
     outPath,
     clientOutPath: req.meta?.clientArtifactPaths?.outPath,
     startedAt: Date.now(),
+    quality: req.flags?.quality,
     showTouches: req.flags?.hideTouches !== true,
     gestureEvents: [],
   };
@@ -180,6 +190,7 @@ async function startRecording(params: {
   }
 
   const fpsFlag = req.flags?.fps;
+  const qualityFlag = req.flags?.quality;
   if (
     fpsFlag !== undefined &&
     (!Number.isInteger(fpsFlag) ||
@@ -191,6 +202,17 @@ async function startRecording(params: {
       `fps must be an integer between ${IOS_DEVICE_RECORD_MIN_FPS} and ${IOS_DEVICE_RECORD_MAX_FPS}`,
     );
   }
+  if (
+    qualityFlag !== undefined &&
+    (!Number.isInteger(qualityFlag) ||
+      qualityFlag < RECORDING_MIN_QUALITY ||
+      qualityFlag > RECORDING_MAX_QUALITY)
+  ) {
+    return errorResponse(
+      'INVALID_ARGS',
+      `quality must be an integer between ${RECORDING_MIN_QUALITY} and ${RECORDING_MAX_QUALITY}`,
+    );
+  }
 
   if (!isCommandSupportedOnDevice('record', device)) {
     return errorResponse('UNSUPPORTED_OPERATION', 'record is not supported on this device');
@@ -299,6 +321,14 @@ async function stopNonRunnerRecording(params: {
     );
   }
 
+  if (recording.quality !== undefined && recording.quality < RECORDING_MAX_QUALITY) {
+    await deps.resizeRecording({
+      videoPath: recording.outPath,
+      quality: recording.quality,
+      targetLabel: 'iOS recording',
+    });
+  }
+
   await finalizeRecordingOverlay({
     recording,
     deps,
diff --git a/src/daemon/handlers/session-replay-script.ts b/src/daemon/handlers/session-replay-script.ts
index f46ec2a3f..cab93df6e 100644
--- a/src/daemon/handlers/session-replay-script.ts
+++ b/src/daemon/handlers/session-replay-script.ts
@@ -243,6 +243,14 @@ function parseReplayScriptLine(line: string): SessionAction | null {
         index += 1;
         continue;
       }
+      if (token === '--quality' && index + 1 < args.length) {
+        const parsedQuality = Number(args[index + 1]);
+        if (Number.isFinite(parsedQuality)) {
+          action.flags.quality = Math.floor(parsedQuality);
+        }
+        index += 1;
+        continue;
+      }
       positionals.push(token);
     }
     action.positionals = positionals;
diff --git a/src/daemon/script-utils.ts b/src/daemon/script-utils.ts
index 2ecd33a5b..8421a6a9a 100644
--- a/src/daemon/script-utils.ts
+++ b/src/daemon/script-utils.ts
@@ -130,6 +130,9 @@ export function appendRecordActionScriptArgs(parts: string[], action: SessionAct
   if (typeof action.flags?.fps === 'number') {
     parts.push('--fps', String(action.flags.fps));
   }
+  if (typeof action.flags?.quality === 'number') {
+    parts.push('--quality', String(action.flags.quality));
+  }
   if (action.flags?.hideTouches) {
     parts.push('--hide-touches');
   }
diff --git a/src/daemon/session-store.ts b/src/daemon/session-store.ts
index c941f62da..01cd15ea6 100644
--- a/src/daemon/session-store.ts
+++ b/src/daemon/session-store.ts
@@ -237,6 +237,7 @@ const SANITIZED_FLAG_KEYS = [
   'saveScript',
   'noRecord',
   'fps',
+  'quality',
   'hideTouches',
   'count',
   'intervalMs',
diff --git a/src/daemon/types.ts b/src/daemon/types.ts
index 6b507e290..b2395795f 100644
--- a/src/daemon/types.ts
+++ b/src/daemon/types.ts
@@ -136,6 +136,7 @@ type SessionRecordingBase = {
   telemetryPath?: string;
   overlayWarning?: string;
   startedAt: number;
+  quality?: number;
   showTouches: boolean;
   gestureEvents: RecordingGestureEvent[];
   touchReferenceFrame?: {
diff --git a/src/platforms/ios/__tests__/recording-scripts.test.ts b/src/platforms/ios/__tests__/recording-scripts.test.ts
index 5e70a3b46..cc5a78526 100644
--- a/src/platforms/ios/__tests__/recording-scripts.test.ts
+++ b/src/platforms/ios/__tests__/recording-scripts.test.ts
@@ -35,6 +35,14 @@ test('recording trim Swift script typechecks', async (t) => {
   await assertSwiftScriptTypechecks(path.join(recordingScriptsDir, 'recording-trim.swift'));
 });
 
+test('recording resize Swift script typechecks', async (t) => {
+  if (process.platform !== 'darwin') {
+    t.skip('Swift recording scripts are only validated on macOS');
+  }
+
+  await assertSwiftScriptTypechecks(path.join(recordingScriptsDir, 'recording-resize.swift'));
+});
+
 test('recording inspect Swift script typechecks', async (t) => {
   if (process.platform !== 'darwin') {
     t.skip('Swift recording scripts are only validated on macOS');
diff --git a/src/platforms/ios/__tests__/runner-client.test.ts b/src/platforms/ios/__tests__/runner-client.test.ts
index 1524bdadc..174437ffa 100644
--- a/src/platforms/ios/__tests__/runner-client.test.ts
+++ b/src/platforms/ios/__tests__/runner-client.test.ts
@@ -135,7 +135,12 @@ const runnerProtocolCommandFixtures: Record<RunnerCommand['command'], RunnerComm
   keyboardDismiss: { command: 'keyboardDismiss' },
   alert: { command: 'alert', action: 'accept' },
   pinch: { command: 'pinch', scale: 0.5 },
-  recordStart: { command: 'recordStart', outPath: '/tmp/runner-recording.mp4', fps: 30 },
+  recordStart: {
+    command: 'recordStart',
+    outPath: '/tmp/runner-recording.mp4',
+    fps: 30,
+    quality: 7,
+  },
   recordStop: { command: 'recordStop' },
   uptime: { command: 'uptime' },
   shutdown: { command: 'shutdown' },
@@ -228,6 +233,7 @@ test('runner protocol fixtures cover every runner command with JSON-safe samples
   assert.equal(roundTrip.screenshot.fullscreen, true);
   assert.equal(roundTrip.rotate.orientation, 'landscape-left');
   assert.equal(roundTrip.recordStart.fps, 30);
+  assert.equal(roundTrip.recordStart.quality, 7);
 });
 
 test('resolveRunnerDestination uses device destination for physical devices', () => {
diff --git a/src/platforms/ios/runner-contract.ts b/src/platforms/ios/runner-contract.ts
index 8c06898fd..14ad83c32 100644
--- a/src/platforms/ios/runner-contract.ts
+++ b/src/platforms/ios/runner-contract.ts
@@ -53,6 +53,7 @@ export type RunnerCommand = {
   scale?: number;
   outPath?: string;
   fps?: number;
+  quality?: number;
   interactiveOnly?: boolean;
   compact?: boolean;
   depth?: number;
diff --git a/src/recording/overlay.ts b/src/recording/overlay.ts
index d10354cd1..bbd394fd6 100644
--- a/src/recording/overlay.ts
+++ b/src/recording/overlay.ts
@@ -30,6 +30,7 @@ function resolveScriptPath(scriptName: string): string {
 
 let overlayScriptPath: string | undefined;
 let trimScriptPath: string | undefined;
+let resizeScriptPath: string | undefined;
 
 export function getRecordingOverlaySupportWarning(
   hostPlatform: NodeJS.Platform = process.platform,
@@ -50,6 +51,11 @@ function getTrimScriptPath(): string {
   return trimScriptPath;
 }
 
+function getResizeScriptPath(): string {
+  resizeScriptPath ??= resolveScriptPath('recording-resize.swift');
+  return resizeScriptPath;
+}
+
 async function exportProcessedVideo(params: {
   videoPath: string;
   scriptPath: string;
@@ -140,3 +146,17 @@ export async function overlayRecordingTouches(params: {
     commandDescription: `Failed to add touch overlays to the ${targetLabel}`,
   });
 }
+
+export async function resizeRecording(params: {
+  videoPath: string;
+  quality: number;
+  targetLabel?: string;
+}): Promise<void> {
+  const { videoPath, quality, targetLabel = 'recording' } = params;
+  await exportProcessedVideo({
+    videoPath,
+    scriptPath: getResizeScriptPath(),
+    scriptArgs: ['--quality', String(quality)],
+    commandDescription: `Failed to resize the ${targetLabel}`,
+  });
+}
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
index 9cb54bdb9..a24dac7bc 100644
--- a/src/utils/__tests__/args.test.ts
+++ b/src/utils/__tests__/args.test.ts
@@ -530,6 +530,15 @@ test('parseArgs recognizes record --fps flag', () => {
   assert.equal(parsed.flags.fps, 30);
 });
 
+test('parseArgs recognizes record --quality flag', () => {
+  const parsed = parseArgs(['record', 'start', './capture.mp4', '--quality', '7'], {
+    strictFlags: true,
+  });
+  assert.equal(parsed.command, 'record');
+  assert.deepEqual(parsed.positionals, ['start', './capture.mp4']);
+  assert.equal(parsed.flags.quality, 7);
+});
+
 test('parseArgs recognizes record --hide-touches flag', () => {
   const parsed = parseArgs(['record', 'start', './capture.mp4', '--hide-touches'], {
     strictFlags: true,
@@ -556,6 +565,16 @@ test('parseArgs rejects invalid record --fps range', () => {
   );
 });
 
+test('parseArgs rejects invalid record --quality range', () => {
+  assert.throws(
+    () => parseArgs(['record', 'start', './capture.mp4', '--quality', '4'], { strictFlags: true }),
+    (error) =>
+      error instanceof AppError &&
+      error.code === 'INVALID_ARGS' &&
+      error.message === 'Invalid quality: 4',
+  );
+});
+
 test('parseArgs recognizes longpress command', () => {
   const parsed = parseArgs(['longpress', '300', '500', '800'], { strictFlags: true });
   assert.equal(parsed.command, 'longpress');
@@ -657,6 +676,7 @@ test('usage includes only global flags in the top-level flags section', () => {
   assert.doesNotMatch(usageText, /--header <name:value>/);
   assert.doesNotMatch(usageText, /--restart/);
   assert.doesNotMatch(usageText, /--fps <n>/);
+  assert.doesNotMatch(usageText, /--quality <5-10>/);
   assert.doesNotMatch(usageText, /--save-script \[path\]/);
   assert.doesNotMatch(usageText, /--metadata/);
 });
@@ -943,7 +963,11 @@ test('open command usage documents macOS desktop surface flags', () => {
 test('command usage shows record touch-overlay opt-out flag', () => {
   const help = usageForCommand('record');
   if (help === null) throw new Error('Expected command help text');
-  assert.match(help, /record start \[path\] \[--fps <n>\] \[--hide-touches\] \| record stop/);
+  assert.match(
+    help,
+    /record start \[path\] \[--fps <n>\] \[--quality <5-10>\] \[--hide-touches\] \| record stop/,
+  );
+  assert.match(help, /--quality <5-10>/);
   assert.match(help, /--hide-touches/);
 });
 
diff --git a/src/utils/command-schema.ts b/src/utils/command-schema.ts
index b1f6f8125..d43d93e0c 100644
--- a/src/utils/command-schema.ts
+++ b/src/utils/command-schema.ts
@@ -63,6 +63,7 @@ export type CliFlags = {
   appsFilter?: 'user-installed' | 'all';
   count?: number;
   fps?: number;
+  quality?: number;
   hideTouches?: boolean;
   intervalMs?: number;
   delayMs?: number;
@@ -551,6 +552,16 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     usageLabel: '--fps <n>',
     usageDescription: 'Record: target frames per second (iOS physical device runner)',
   },
+  {
+    key: 'quality',
+    names: ['--quality'],
+    type: 'int',
+    min: 5,
+    max: 10,
+    usageLabel: '--quality <5-10>',
+    usageDescription:
+      'Record: scale recording resolution from 5 (50%) through 10 (native resolution)',
+  },
   {
     key: 'hideTouches',
     names: ['--hide-touches'],
@@ -1298,12 +1309,13 @@ const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     allowedFlags: [],
   },
   record: {
-    usageOverride: 'record start [path] [--fps <n>] [--hide-touches] | record stop',
+    usageOverride:
+      'record start [path] [--fps <n>] [--quality <5-10>] [--hide-touches] | record stop',
     listUsageOverride: 'record start [path] | record stop',
     helpDescription: 'Start/stop screen recording',
     summary: 'Start or stop screen recording',
     positionalArgs: ['start|stop', 'path?'],
-    allowedFlags: ['fps', 'hideTouches'],
+    allowedFlags: ['fps', 'quality', 'hideTouches'],
   },
   trace: {
     usageOverride: 'trace start [path] | trace stop [path]',
diff --git a/website/docs/docs/client-api.md b/website/docs/docs/client-api.md
index f517aa715..d5669c986 100644
--- a/website/docs/docs/client-api.md
+++ b/website/docs/docs/client-api.md
@@ -136,6 +136,8 @@ Additional CLI-backed methods are exposed on their domain groups with typed opti
 - `client.recording.record()` and `client.recording.trace()`
 - `client.settings.update()`
 
+`client.recording.record({ action: 'start', path, quality: 5 })` starts a smaller 50% resolution video; omit `quality` to keep native/current resolution.
+
 ## Android `installFromSource()`
 
 ```ts
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index 9a0345bb0..6f31426e1 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -547,6 +547,7 @@ agent-device diff screenshot --baseline baseline.png --out diff.png --overlay-re
 agent-device record start               # Start screen recording to auto filename
 agent-device record start session.mp4   # Start recording to explicit path
 agent-device record start session.mp4 --fps 30  # Override iOS device runner FPS
+agent-device record start session.mp4 --quality 7 # Scale recording resolution to 70%
 agent-device record stop                # Stop active recording
 ```
 
@@ -615,6 +616,7 @@ tail -50 ~/.agent-device/sessions/default/app.log
 - Physical iOS device capture is best-effort: dropped frames are expected and true 60 FPS is not guaranteed even with `--fps 60`.
 - Physical-device capture defaults to 15 FPS.
 - `--fps <n>` (1-120) applies to physical iOS device recording as an explicit FPS cap.
+- `--quality <5-10>` scales recording resolution from 50% through native resolution without changing FPS. Omitting it preserves the platform's current/native recording resolution.
 
 ## Tracing
 
diff --git a/website/docs/docs/configuration.md b/website/docs/docs/configuration.md
index e809f270f..87ee69126 100644
--- a/website/docs/docs/configuration.md
+++ b/website/docs/docs/configuration.md
@@ -79,7 +79,7 @@ Common keys include:
 - `verbose`
 - `json`
 
-Command-specific defaults are supported too, for example `snapshotDepth`, `snapshotScope`, `activity`, `relaunch`, `shutdown`, `fps`, `stepsFile`, or `saveScript`.
+Command-specific defaults are supported too, for example `snapshotDepth`, `snapshotScope`, `activity`, `relaunch`, `shutdown`, `fps`, `quality`, `stepsFile`, or `saveScript`.
 
 Bound-session defaults use the same config and env mapping too:
 - `sessionLock` -> `AGENT_DEVICE_SESSION_LOCK`
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index 565cedad5..76bc2dae5 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -31,6 +31,7 @@ For exploratory QA and bug-hunting workflows, see `skills/dogfood/SKILL.md` in t
   - Physical devices use runner screenshot capture (`XCUIScreen.main.screenshot()` frames) stitched into MP4, so FPS is best-effort (not guaranteed 60 even with `--fps 60`).
   - Physical-device recording requires an active app session context (`open <app>` first).
   - Physical-device recording defaults to 15 FPS and supports `--fps` caps.
+  - `record start --quality <5-10>` scales recording resolution from 50% through native resolution; omitting it keeps native/current resolution.
 - Android supports the same core interaction set, plus `rotate`, `push` notification simulation, `clipboard read/write`, and `keyboard status|get|dismiss`.
 - iOS supports `keyboard dismiss` through the XCTest runner when the on-screen keyboard is visible.
 - App-event triggers are available on iOS and Android through app-defined deep-link hooks (`trigger-app-event`), using active session context or explicit device selectors.

From 5025759e1f8401008eb6f42d7c315622bc2a8539 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 14 Apr 2026 09:42:34 +0200
Subject: [PATCH 2/4] test: cover quality edge cases

---
 .../handlers/__tests__/record-trace.test.ts   | 153 ++++++++++++++++++
 src/daemon/handlers/record-trace-finalize.ts  |   4 +-
 src/daemon/handlers/record-trace-recording.ts |  16 +-
 src/utils/__tests__/args.test.ts              |  11 ++
 4 files changed, 176 insertions(+), 8 deletions(-)

diff --git a/src/daemon/handlers/__tests__/record-trace.test.ts b/src/daemon/handlers/__tests__/record-trace.test.ts
index d07466706..e95882cc4 100644
--- a/src/daemon/handlers/__tests__/record-trace.test.ts
+++ b/src/daemon/handlers/__tests__/record-trace.test.ts
@@ -790,6 +790,42 @@ test('record stop resizes iOS simulator recording when quality is explicit', asy
   });
 });
 
+test('record stop skips iOS simulator resize when quality is 10', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-quality-max';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  mockRunCmdBackground.mockImplementation(() => ({
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  }));
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim-max.mp4'],
+    flags: { quality: 10 },
+  });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(responseStop?.ok).toBe(true);
+  expect(mockResizeRecording).not.toHaveBeenCalled();
+});
+
 test('record stop keeps iOS simulator video when overlay export fails', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim-overlay-warning';
@@ -830,6 +866,46 @@ test('record stop keeps iOS simulator video when overlay export fails', async ()
   );
 });
 
+test('record stop keeps iOS simulator video when resize export fails', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim-resize-fail';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  mockRunCmdBackground.mockImplementation(() => ({
+    child: { kill: () => {} } as any,
+    wait: Promise.resolve({ stdout: '', stderr: '', exitCode: 0 }),
+  }));
+
+  mockResizeRecording.mockImplementation(async () => {
+    throw new Error('resize failed');
+  });
+
+  await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './sim-resize-fail.mp4'],
+    flags: { quality: 6 },
+  });
+
+  const responseStop = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['stop'],
+  });
+
+  expect(responseStop?.ok).toBe(true);
+  expect((responseStop as any).data?.overlayWarning ?? '').toMatch(/failed to resize recording/i);
+});
+
 test('record start does not fail when iOS simulator runner warm-up fails', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'ios-sim-warm-failure';
@@ -1002,6 +1078,83 @@ test('record start passes scaled Android screenrecord size when quality is expli
   expect(sessionStore.get(sessionName)?.recording?.quality).toBe(7);
 });
 
+test('record start rejects Android quality when wm size is unparseable', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-quality-unparseable';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    const command = args.join(' ');
+    if (command === '-s emulator-5554 shell wm size') {
+      return { stdout: 'w=oops\n', stderr: '', exitCode: 0 };
+    }
+    return { stdout: '', stderr: '', exitCode: 0 };
+  });
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android.mp4'],
+    flags: { quality: 7 },
+  });
+
+  expect(response?.ok).toBe(false);
+  expect((response as any).error?.code).toBe('COMMAND_FAILED');
+});
+
+test('record start does not scale Android screenrecord when quality is 10', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'android-quality-max';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'android',
+      id: 'emulator-5554',
+      name: 'Android',
+      kind: 'device',
+      booted: true,
+    }),
+  );
+
+  const adbCommands: string[] = [];
+  mockRunCmd.mockImplementation(async (_cmd, args) => {
+    const command = args.join(' ');
+    adbCommands.push(command);
+    if (
+      /^-s emulator-5554 shell screenrecord \/sdcard\/agent-device-recording-\d+\.mp4 >\/dev\/null 2>&1 & echo \$!$/.test(
+        command,
+      )
+    ) {
+      return { stdout: '4321\n', stderr: '', exitCode: 0 };
+    }
+    if (
+      /^-s emulator-5554 shell stat -c %s \/sdcard\/agent-device-recording-\d+\.mp4$/.test(command)
+    ) {
+      return { stdout: '1024\n', stderr: '', exitCode: 0 };
+    }
+    return { stdout: '', stderr: '', exitCode: 0 };
+  });
+
+  const response = await runRecordCommand({
+    sessionStore,
+    sessionName,
+    positionals: ['start', './android-max.mp4'],
+    flags: { quality: 10 },
+  });
+
+  expect(response?.ok).toBe(true);
+  expect(adbCommands).not.toContain('-s emulator-5554 shell wm size');
+});
+
 test('record start scales Android screenrecord from override size when present', async () => {
   const sessionStore = makeSessionStore();
   const sessionName = 'android-override-quality';
diff --git a/src/daemon/handlers/record-trace-finalize.ts b/src/daemon/handlers/record-trace-finalize.ts
index 08508dcdb..f311a7638 100644
--- a/src/daemon/handlers/record-trace-finalize.ts
+++ b/src/daemon/handlers/record-trace-finalize.ts
@@ -29,7 +29,7 @@ export async function finalizeRecordingOverlay(
   if (recording.showTouches) {
     const overlaySupportWarning = getRecordingOverlaySupportWarning();
     if (overlaySupportWarning) {
-      recording.overlayWarning = overlaySupportWarning;
+      recording.overlayWarning ??= overlaySupportWarning;
     } else {
       try {
         await deps.overlayRecordingTouches({
@@ -38,7 +38,7 @@ export async function finalizeRecordingOverlay(
           targetLabel,
         });
       } catch (error) {
-        recording.overlayWarning = `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
+        recording.overlayWarning ??= `failed to overlay recording touches: ${formatRecordTraceError(error)}`;
       }
     }
   }
diff --git a/src/daemon/handlers/record-trace-recording.ts b/src/daemon/handlers/record-trace-recording.ts
index 0c4b53ff2..71704705b 100644
--- a/src/daemon/handlers/record-trace-recording.ts
+++ b/src/daemon/handlers/record-trace-recording.ts
@@ -21,7 +21,7 @@ import {
   trimRecordingStart,
 } from '../../recording/overlay.ts';
 import { buildSimctlArgsForDevice } from '../../platforms/ios/simctl.ts';
-import { formatRecordTraceExecFailure } from '../record-trace-errors.ts';
+import { formatRecordTraceError, formatRecordTraceExecFailure } from '../record-trace-errors.ts';
 import { finalizeRecordingOverlay } from './record-trace-finalize.ts';
 import { errorResponse } from './response.ts';
 import { startAndroidRecording, stopAndroidRecording } from './record-trace-android.ts';
@@ -322,11 +322,15 @@ async function stopNonRunnerRecording(params: {
   }
 
   if (recording.quality !== undefined && recording.quality < RECORDING_MAX_QUALITY) {
-    await deps.resizeRecording({
-      videoPath: recording.outPath,
-      quality: recording.quality,
-      targetLabel: 'iOS recording',
-    });
+    try {
+      await deps.resizeRecording({
+        videoPath: recording.outPath,
+        quality: recording.quality,
+        targetLabel: 'iOS recording',
+      });
+    } catch (error) {
+      recording.overlayWarning = `failed to resize recording: ${formatRecordTraceError(error)}`;
+    }
   }
 
   await finalizeRecordingOverlay({
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
index a24dac7bc..835746ff1 100644
--- a/src/utils/__tests__/args.test.ts
+++ b/src/utils/__tests__/args.test.ts
@@ -539,6 +539,17 @@ test('parseArgs recognizes record --quality flag', () => {
   assert.equal(parsed.flags.quality, 7);
 });
 
+test('parseArgs accepts record --quality boundaries', () => {
+  const parsedMin = parseArgs(['record', 'start', './capture.mp4', '--quality', '5'], {
+    strictFlags: true,
+  });
+  assert.equal(parsedMin.flags.quality, 5);
+  const parsedMax = parseArgs(['record', 'start', './capture.mp4', '--quality', '10'], {
+    strictFlags: true,
+  });
+  assert.equal(parsedMax.flags.quality, 10);
+});
+
 test('parseArgs recognizes record --hide-touches flag', () => {
   const parsed = parseArgs(['record', 'start', './capture.mp4', '--hide-touches'], {
     strictFlags: true,

From e586b28aff3015a3d01f464ce5a69fa0a6ba45f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Tue, 14 Apr 2026 10:32:05 +0200
Subject: [PATCH 3/4] fix: scale transform translation in resize

---
 .../RecordingScripts/recording-resize.swift     | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
index 7efe1f568..de489539d 100644
--- a/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
+++ b/ios-runner/AgentDeviceRunner/RecordingScripts/recording-resize.swift
@@ -68,10 +68,8 @@ func run() throws {
   let instruction = AVMutableVideoCompositionInstruction()
   instruction.timeRange = fullRange
   let layerInstruction = AVMutableVideoCompositionLayerInstruction(assetTrack: compositionVideoTrack)
-  // Keep rotation/translation from the source track, then scale into the smaller render canvas.
-  let scaledTransform = sourceVideoTrack.preferredTransform.concatenating(
-    CGAffineTransform(scaleX: scale, y: scale)
-  )
+  // Scale the full preferred transform (including translation) to match the smaller render canvas.
+  let scaledTransform = scaledPreferredTransform(sourceVideoTrack.preferredTransform, scale: scale)
   layerInstruction.setTransform(scaledTransform, at: .zero)
   instruction.layerInstructions = [layerInstruction]
   videoComposition.instructions = [instruction]
@@ -171,3 +169,14 @@ func resolvedFrameDuration(for track: AVAssetTrack) -> CMTime {
 
   return CMTime(value: 1, timescale: 60)
 }
+
+func scaledPreferredTransform(_ transform: CGAffineTransform, scale: CGFloat) -> CGAffineTransform {
+  CGAffineTransform(
+    a: transform.a * scale,
+    b: transform.b * scale,
+    c: transform.c * scale,
+    d: transform.d * scale,
+    tx: transform.tx * scale,
+    ty: transform.ty * scale
+  )
+}

From 5cce83bdb2f096aea1f2f22b1e122fa10ec3c7d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Wed, 15 Apr 2026 13:10:57 +0200
Subject: [PATCH 4/4] fix: narrow recording quality flag

---
 src/cli/commands/generic.ts | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/cli/commands/generic.ts b/src/cli/commands/generic.ts
index 14df6884a..7e3277f71 100644
--- a/src/cli/commands/generic.ts
+++ b/src/cli/commands/generic.ts
@@ -5,6 +5,7 @@ import type {
   FindOptions,
   IsOptions,
   PermissionTarget,
+  RecordOptions,
   SettingsUpdateOptions,
 } from '../../client-types.ts';
 import { announceReplayTestRun } from '../../cli-test.ts';
@@ -205,7 +206,7 @@ export const genericClientCommandHandlers = {
         action: readStartStop(positionals[0], 'record'),
         path: positionals[1],
         fps: flags.fps,
-        quality: flags.quality as 5 | 6 | 7 | 8 | 9 | 10 | undefined,
+        quality: readRecordingQuality(flags.quality),
         hideTouches: flags.hideTouches,
       }),
   ),
@@ -347,6 +348,12 @@ function readStartStop(value: string | undefined, command: string): 'start' | 's
   throw new AppError('INVALID_ARGS', `${command} requires start|stop`);
 }
 
+function readRecordingQuality(value: number | undefined): RecordOptions['quality'] {
+  if (value === undefined) return undefined;
+  if ([5, 6, 7, 8, 9, 10].includes(value)) return value as RecordOptions['quality'];
+  throw new AppError('INVALID_ARGS', `Invalid quality: ${value}`);
+}
+
 function readLogsAction(
   value: string | undefined,
 ): 'path' | 'start' | 'stop' | 'doctor' | 'mark' | 'clear' | undefined {